ACOMTools

ACOMTools 1.5 development guide

This documentation provides information for the developers interested in:

  • Integration of other software with ACOMTools
  • Extending ACOMTools functionality
  • Writing software that communicates with ACOM products
  • Integration of control modules for another hardware products in the ACOMTools

Before reading the documentation

On the above picture you can see the main layout of the ACOMTools. More layouts will be supported soon but we will use this one as starting point for the definitions.

Left part marked with 1 is the constant UI part. It represents the amplifier and antenna switch. Antenna panel can be hidden and colors may vary - visual components support configuration thus actual view may differ in details.

Right panel marked with 2 is the extensions UI holder tab control. It holds the UI parts of the loaded service extensions. Actual count of the pages in it may vary depending on the installed and loaded extensions. User is able to enable only those extensions that will be useful for him/her. Panel can be detached or/and hidden. In alternate views (appbar/slim view) this panel is assumed to be detached and to be shown or hidden on user request. In detached mode it can be resized and maximized.

Configuration

You can access the configuration options from the view menu. See the General options and Extensions. User's manual contains more configuration about the configuration.

Understanding ACOMTools

ACOMTools software is not a closed application it is an environment that supplies data and functionality to service components called for simplicity also just "extensions".

Functional parts of the ACOMTools

  1. Frame application (Frame)
  2. Core script (Core)
  3. USPC communication components (USPC)
  4. Service extensions (Extensions)

Frame is the most important part - it consist of:

  • constant UI that represents the ACOM 2000A amplifier and antenna switch
  • service extensions environment API and management code
  • core script support API and management code
  • automation objects allowing access to the application from outside

Frame groups all the API objects and serves them to the core script and extensions. It manages the USPC connection components in order to provide access to the ACOM hardware and serves them to the extensions and core. Frame itself does not contain any controlling code and leaves that work to the core script and extensions. Thus the exact functionality of the ACOMTools installed on a particular machine depends on the service extensions installed. User is able to select what functionality to enable in the application and depending on his/her needs the ACOMTools can be equipped with different sets of extensions.

Core script is written in JScript but it can be written in VBScript too. Its mission is to provide functionality for the constant UI and to provide API functions and data to the extensions. In general Core can be extended with new functions and helper code and data and will grow in time.

USPC (Unified Streaming Packet Communication) components is a COM based standard developed and maintained by newObjects. The standard specification is in beta state. No major changes are expected and compatibility will be kept in future. Its purpose is to supply an abstraction layer for the packet oriented communications over any medium. ACOMTools is equipped by default with only serial USPC driver but there is no problem to replace driver with any other USPC transfer component and thus allow ACOMTools to use resources of remote machines for example. As any software based on USPC ACOMTools will be able to benefit from the USPC architecture by using components from different vendors when they become available.

Extensions - can be written in script or as COM components. Frame manages their lifetime and broadcasts events to them. They are able to access all the functionality of the frame and core script. Extensions may consist of 3 parts:

  • Service component or script (required).
  • Extension UI (optional). If it exist it is shown in the extensions applet. UI can be implemented as visual ActiveX/OCX or as DHTML page
  • Configuration HTML dialog (optional). Required in the extensions needs configuration settings.

Frame supplies extensions with a persistent manager object that allows them to save/restore their settings. In current version this object uses the registry.


Extensions object model

Extensions access the functionality provided by the Frame, core and USPC components through objects supplied by the frame to them.

Object model access

Extensions written in script (JScript, VBScript) access the object model through namespaces available to them immediately after loading.

Extensions written as COMponents receive interface pointers to the objects through predefined routines. These methods are called through the IDispatch interface by name always. You don't need to take care about their DISPID and binary compatibility. Any COM compliant development tool can be used (C++, VB, Delphi, WSC and so on).

Object model is accessible directly only for the service part of the extension. Extension UI is controlled by it thus if direct access is required all or some of the objects can be passed to it by the service part of the extension.

In scripts object namespaces are accessible through globally available names (see the actual names at the right side of the page). Examples:

Dim switch
Set switch = ACOMTools.AntPannel
' Saves reference to the antenna switch in a local variable

ACOMTools.PlaySound(2)
'plays a sound

In extensions implemented as COM objects these objects are received as parameters of the methods provided by the extension through its main IDisptach interface:

OnSetApp method passes ACOMTools object

OnSetSettings method passes Settings object

Both methods are optional and if some of them is not found Frame assumes that extension doesn't need the corresponding object. For example if you are implementing a decorative extension showing some pictures you will not need to the ACOMTools and you can omit OnSetApp method implementation.

Objects reference

ACOMTools - main object. Gives access to other objects, core, constant UI and USPC components.
 | AmpPannel - Amplifier panel object - part of the constant UI
 | AntPannel - Antenna switch pannel object - part of the constant UI
 | Core - core script as object. Every function or object defined globally in the core is accessible. This documentation covers only methods/data defined especially for use by the extensions.
 | bgColor - retrieves dialog background color. If you want to synch colors of your GUI and/or configuration dialog you can use it.
 | fgColor - retrieves dialog foreground color. If you want to synch colors of your GUI and/or configuration dialog you can use it.
 | Group - retrieves the group ID of the PC in the ACOM network. That is the default amplifier ID - recommended to use if you are creating packets manually.
 | Type - Device type pf the PC in the ACOM network. In nearly all cases this will be 112 but it is recommended to use the value instead of hardcoding it.
 | MoveMainWindow - Moves the main application window in certain layout modes.
 | PlaySound - Plays predefined sounds. Recommended to use them for user notifications.
 | RaiseEvent - Broadcasts event to all the extensions. You can use the method to communicate with other extensions.
 | RaiseUIError - Broadcasts text messages dedicated for the user attention. There is an extension that shows them. It is recommended to use this method for alert notifications instead of opening alert messages directly. This gives the user ability to deny/allow them.
 | Transmit - Transmits packet/command to the ACOM network.
Settings - Initialized object that allows the extension to write/read its own settings to a location managed by the frame. It is recommended to use that object instead of saving data directly to the registry or file. If data amount is too big then you can create a file and save its location through the object.
 | Item (Default, indexed property) - sets/retrieves a string value by name
 | Option (indexed property) - sets retrieves integer value by name


Automation object model

ACOMTools can be accessed by external applications through its automation objects. Automation object model is only a gateway to the another objects - the same objects that can be used by the extensions.

ACOMTools is not a document oriented application thus its automation objects are a kind of proxies. External application creates the desired object and accesses through it the resting ACOMTools objects. (see the reference at the right)

Sample (JScript for Windows Scripting Host)

You must create ACOMTools objects - using the CreateObject (VBS), new ActiveXObject (JScript), CoCreateInstance (COM API) instead of accessing them (using GetObject for example).

Using that mechanism allows ACOMTools to extend its object model in future without making the old automation applications incompatible with it.

Objects reference

ACOMTools API - main automation object. Gives access to other objects, core, constant UI and USPC components.
 | core - returns the Core script object
 | extAdvisor - returns the ACOMTools object
 | extensions - returns the extensions collection. You can load/unload extensions through it
 | Objects for advanced usage
 | receiver
 | translator
 | driver
ExtInstaller - Object that allows external programs to install extensions at run time. The class supports only installation if you want to start/stop an extension use the ACOMTools API object to access the extensions collection.
 | InstallFromFile
 | Language
 | RegisterServer
 | gui
 | autoStart
 | cfg
 | script
 | clsid
 | Install


ACOMTools

What is USPC?

(read this if you want a bit more general information. If not - see the right side of the page)

I'll not try to describe USPC completely here. A full documentation will be published on the newObjects' site at later time. In order to use USPC in ACOMTools only a little knowledge about USPC is enough.

USPC stands by Unified Streaming Packet Communication. It is a simple 3-layer standard developed by us. Its target is to expose abstract communication to the applications and to allow them to use packet oriented communication without knowing the specifics of the physical/logical media (it is possible to cover some non-packet oriented communication protocols too). For example ACOMTools ships with USPC driver component for serial ports (RS-232 compatible) but it will work without changes with TCP USPC driver (planned for release).

USPC was developed only 2 months ago in order to make possible to complete several projects with less human resources. The idea works fine and we are going to supply several standard USPC components and a set of USPC drivers in near future.

Layers

Lower layer was called driver or transfer layer. USPC Drivers (or also called transfer controls) are required to support asynchronous data transfer. Support for synchronous transfer is optional.

USPC drivers do the basic data transfer and buffering. They transfer passed data out (write to stream) asynchronously (synchoronous mode is optional) and are able to invoke translators (2-nd level USPC) using some simple universal rules about the buffer. Rules support is required for optimization.

USPC Translators are the middle level. Typically they are protocol specific. Translators are notified by the USPC drivers when data received meets the criteria passed to the driver by the tranlator (on initialization) and translators must construct packet objects and fire them as COM events to the 3-d level.

USPC translators can be universal too.For example we plan dispatch translators that allow many translator objects to work with the same driver and the same connection, proxy translators implementing dummy translator and USPC driver at the same time and so on.

Packet objects are protocol specific. Usually packets are the object representation of the protocol packets. They are planned once and used by all the applications using that protocol.

Application level - needs only to implement USPC events sink. It can be implemented as COM object in a dll that makes a bit more translation and provides some routins or can be implemented in the application directly. In other words in this level everything depends on the developer choice and only event sink is standard.

Threading model. Drivers and translators must be implemented as in-process free threaded COM objects. This is important for the communication with the hardware. Using appartment threaded objects slows the performance thus drivers expect tranlsators to be free-threaded. The threading model of the packet objects is not defined as requirement. It is recommended to use free threaded implementation if you expect usage of the protocol in some kind of server software. Typically packet classes and translator that generates them will be implemented in one dll.

Conclusion. The application that uses USPC needs a driver (or drivers) and translator and packet components. Packets and translator are planed for the protocol and they are able to work with any USPC driver.

USPC Components for ACOM hardware

Translator - Translates the data to/from packet objects and communicates with the USPC driver. Translator object supports several interfaces but they are managed by the ACOMTools internaly and will not be described here.

If you are communicating with the ACOM hardware you can use the ACOMTools.Transmit method. Packet notifications are sent to your code through calls of the methods supplied by the extension. Thus the you will not need to use the Translator object directly as long as you don't need to create USPC connection to another hardware.

Methods

Method Transmit is the only method that you will need to use directly.

Syntax: Transmit(packet_object)

packet_object parameter is a reference to previously initialized packet object (see below).

Transmit method checks the packet_object for errors and translates it to binary data. Then it transmits it using the attached USPC driver (see USPCDriver).

Events

Translator fires the following events:

PacketReceived(packet_object) - passes to the sink received packet. In ACOMTools there is an application object that sinks those events. You will never need to handle this event directly for the ACOM hardware. If you are going to implement extension that controls another hardware using USPC please review the USPC documentation.

StateNotify(StateFlags,strStateText) - this event is fired optionaly by the USPC tranlsators. There is no need to handle it - ACOMTools deals with it internaly.

ACOMTools USPC Packet

Code that needs to use the ACOM protocol directly must use the Packet object. It encapsulates the ACOM hardware commands.

Properties
 | param (Default indexed property) - read/write translated parameters to the packet. Must be used onlyif the comamnd is already specified.
 | packetType - specifies the type of the packet.
 | rxType - Type of the addressed (target) device
 | rxGroup - Group ID of the target device
 | txType - Type of the source device
 | txGroup - Group ID of the source device
 | command - Command name
 | paramString - Contains the raw parameter string. Use it only for the commands without support for the param property. (Some of the rarely used commands are not parsed)
 | volume - Meaningful only for the indicator packets (forward and reflected power)
 | incomming - incomming or outgoing packet
 | isBroadcast - helper property
 | paramCount - returns the param count (se also param property)

See example code that prepares a packet for sending and example code that processes a received packet at the Using Packet Objects page.


Using Packet Objects

Packet objects can be created directly by using their progID: "newObjects.USPC.ACOMSerialProtocolPacket" or by using the core API function Packet.

Sample (in extension):

Dim packet
Set packet=ACOMTools.CreateObject("newObjects.USPC.ACOMSerialProtocolPacket")

You can use also the language specific ActiveX creation routines - CreateObject in VBScript and new ActiveXObject in JScript.

Using the method supplied by the Core object - Packet - you are able to create packet that is correctly initialized with the Group ID and Type ID of the ACOMTools application. It is recommended to use that method if you are communicating with the default hardware group configured with the ACOMTools application. Usage of the Packet method is also reasonable if you are developing an extension that controls a secondary amplifier or/and antenna switch not known for the ACOMTools application. Avoiding its usage is reasonable only if your extension simulates another device - with separate Group ID or/and Type ID.

Sample code for Packet method:

Dim packet
Set packet = ACOMTools.Core.Packet(ACOMTools.Type,ACOMTools.Group,"X1")
packet.param(0) = "Hello!"
ACOMTools.Transmit(packet)
' Sample code sets the LED text of the amplifier to "Hello!"
' Note that ACOMTools.Transmit method is used here

In the above example Packet method initializes the packet object with all the addresses and the command name. Extension code must supply only the parameters. When created packet is not-incoming i.e. it is outgoing packet. You can explicitly change this behavior by setting the incomming property to true (before using the param property) and thus simulate incomming packets that are not received physically.

Sample - simple packet processing (JScript).

function OnPacketReceived(p) {
if (p.packetType == 0) {
switch(p.command) {
case "W1":
ACOMTools.AmpPannel.alert("Current antenna switch position is " +
p.param(1))
break;
case "W4":
ACOMTools.AmpPannel.alert("Current antenna switch position is " +
p.param(0))
break;
}
}
}

The above code implements OnPacketReceived extension method. It shows an alert message that shows the current antenna switch position.


ACOMTools Object

Properties

AmpPannel

Returns AmpPannel object

AntPannel

Returns AntPannel object

Core

Returns Core script object

bgColor

Returns OLE_COLOR of the default background color of the ACOMTools application. Usually it should be the dialog background color.

Syntax: variable = ACOMTools.bgColor

Remarks:

Note that in DHTML colors are reversed - i.e. in OLE_COLOR order of the colors is RGB in DHTML it is BGR.

fgColor

Returns OLE_COLOR of the default foreground color of the ACOMTools application. Usually it should be the dialog foreground color.

Syntax: variable = ACOMTools.fgColor

Remarks:

Note that in DHTML colors are reversed - i.e. in OLE_COLOR order of the colors is RGB in DHTML it is BGR.

Group

Returns the configured Group ID for the ACOMTools application. You can use it to set the rxGroup of the packet objects that will be transmitted to the default hardware group.

Syntax: variable = ACOMTools.Group

Sample:

packet.rxGroup = ACOMTools.Group

Type

Returns the configured type of the PC controller in the ACOM hardware network. It should be 112 - PC but it is possible in some specific cases to be changed in order to simulate another hardware

MoveMainWindow

Moves the main ACOMTools window to the specified position. The window will be moved only in certain view modes.

Syntax: ACOMTools.MoveMainWindow(x,y)
x - x screen coordinate of the upper left corner of the window
y - y screen coordinate of the upper left corner of the window

PlaySound

Plays a predefined sound as specified by the parameter. Recommended to use instead of implementing your own play sound method.

Syntax: ACOMTools.PlaySound(n)

Where n is the ID of the predefined sound:
0 - information
1 - warning
2 - error

RaiseEvent

Raises an event that will be distributed to all the extensions that are currently run.

Syntax: ACOMTools.RaiseEvent(name,data)
name - is a string that specifies the name of the event. If you want to be absolutely sure that the name will be unique generate an UUID in string format and use it.
data - can be anything. It depends on your choice and on the purpose of the event.

Remarks:

ACOMTools sends the event through the OnEvent method of all the running extensions. Using events you are able to communicate with another extensions that expect your event. Data assumed for the event can be sent through the data parameter. It is recommended to not send object references through it if the extensions handling that event will save that reference. See OnEvent Method for more details on processing events.

RaiseUIError

Raises specific event that holds only a textual message. There is a standard extension that handles it but it is allowed to handle that event in your extensions (using the OnUIError method). Using that method to "show" error messages allows the user to disable them or allows him to use custom UIError handler.

Syntax: ACOMTools.RaiseUIError(level,text)
level - a number that specifies the type of the error: 0 - no error(information), 1 - warning, 2 - error
text - string describing the error

Remarks:

Using that method instead of showing alerts directly allows the behavior of the error messages to be controlled by the UI error handling extension(s).

Transmit

Transmits a packet object through the default (internal) USPC connection.

Syntax: ACOMTools.Transmit(packet_object)
packet_object - previously created/initialized packet object (see Core.Packet method)

Remarks:

You should use that method to transmit commands to the ACOM hardware as long as your extension does not implement connection to additional hardware not known for the ACOMTools application (on additional COM port for example). ACOMTools prepares Translator object and this method calls its Transmit method - you do not need to deal with the translator directly.

IsConnected

Returns true/false indicating if the application is connected to the COM port.

acomConstant(name)

Indexed property. Returns different constants of general interest for the extensions. Returned value is packed in a VARIANT.
name is a string containing the constant name. Currently defined constants:

Version - (numeric) ACOMTools version
AmpTypeID - Type id of the ACOM amplifiers. Used in the type address fields of the USPC packets.
AntTypeID - Type id of the ACOM antenna switch units. Used in the type address fields of the USPC packets.
PCTypeID - Type id of the PC controllers in the ACOM network. Used in the type address fields of the USPC packets.


AmpPannel Object

AmpPannel object represents the amplifier panel. It consist of many indicators. Two kind of components are used in the panel: VolumeIndicator and SimpleColorCheckBox. All the elements implemented using the SimpleColorCheckBox are able to fire events when clicked. The core configures them during the application start up. It is not recommended to change their behavior from an extension because this will cause collisions with the core (see the SimpleColorCheckBox reference for details). Events fired by the elemets are passed to the extensions through calls to some predefined routines.

Properties

Item(element_name)
Default indexed property. Returns reference to an element on the Amplifier panel.
element_name is a string that can be one of those keywords:

  • ForwardPower - Forward power volume indicator.
  • ReflectedPower - Reflected power volume indicator.
  • Prot - Protection color box
  • Heater - Heater indication color box
  • Plate - plate indicator
  • Drive - Drive indicator
  • Opr - Operate mode indicator
  • Stby - "Stand by" indicator
  • Comm - Comm port is-alive indicator
  • Power - Power indicator
  • Frequency - Freaquency status indicator
  • Misc, Antenna, T - second (yellow) indicator. Currently used for temperature indication
  • Status - The long most status indicator. Used for miscellaneous information.

An example:
ACOMTools.AmpPannel("Status").Text = "Hello world"

Sets the text of the status indicator to "Hello world"

See also:
Forward power and Reflected power volume indicators are implemented using the VolumeIndicator control
All other elements are SimpleColorCheckBox controls

text(index)
Indexed property. Sets/gets the text of the static texts used on the Amplifier panel. These static labels are two.
index can be number or string. Number can be 0 or 1 (in this version) and names of the labels are "Text1" and "Text2".

An example:
ACOMTools.AmpPannel.text("Text1") = "Some text"

It is not recommended to set this property from an extension because core sets these text labels.

Methods

alert(text)
Method - shows a simple alert box with the text supplied in the text parameter. Any already visible alert box is closed before showing the new one. Can be used to show messages to the user. It is recommended (but not required - this is just a style guideline) to avoid it in extensions and use RaiseUIError instead.


AntPannel Object


Core Object


Settings Object

Passed to the extensions (and Core script) by the ACOMTools application. Script extensions refer it through a global namespace named Settings, ActiveX extensions receive it through call to the OnSetSettings method of their IDispatch (The call is the first call made by the ACOMTools when extension is loaded).

Extensions should use that object to store/restore their settings to a storage managed by the ACOMTools application. ACOMTools is responsible for appropriate initialization of the object for the corresponding extension - extension only needs to use the object.

Properties

Item (Default, indexed property)

Sets/Gets a string value from the storage by name.

Syntax:
variable = Settings(name)
Settings(name) = variable

variable - receives/contains the string obtained/saved from/to the storage
name - name of the value. Extension uses that name as ID of the saved/restored value.

Option (indexed property)

Sets/Gets an integer 32-bit numeric value to/from the storage

Syntax:
variable = Settings.Option(name)
Settings.Option(name) = variable

Extension may choose to convert the value to any compatible type. When saving value is converted to 32-bit integer.


Volume Indicator control
Control supports IPersistPropertyBag and can be used in property bag enabled hosts.

Register the control's DLL and see the sample page.

Component class ID is: {37A13A71-B41C-4B48-8A38-A12FA0447BE4}
ProgID is: newObjects.ui.VolumeIndicator

BackColor | OLE_COLOR color | Stock property - background color Default: white
ForeColor | OLE_COLOR color | Stock property - foreground color Default: black
NormalColor | OLE_COLOR color | Color of the segments that are in the normal area. This is the "off" color Default: Dark green
OverloadColor | OLE_COLOR color | Color of the segments that are in the overload area. This is the "off" color Default: Dark red
NormalColorLight | OLE_COLOR color | Color of the segments that are in the normal area. This is the "on" color Default: light green
OverloadColorLight | OLE_COLOR color | Color of the segments that are in the overload area. This is the "on" color Default: light red
Steps | VT_I4 integer number | Number of the segments of the indicator Default: 16
StepsNormal | VT_I4 integer number | Number of the normal segments - must be less than Steps. Specifies the number of the segments/steps on the left representing the normal levels Default: 10
Volume | VT_R4 floating point number | Mostly useful for run-time usage. Specifies the current volume. Indicator lights the appropriate segments in order to indicate it. It must be in the range specified by the LabelStart and LabelEnd. Volumes out fo the range will be cause displaying 0 or maximum. Default: 12.5
LabelStart | VT_R4 floating point number | Minimum volume - corresponds to "0" (zero) - i.e. no segments switched on. Default: 0
LabelEnd | VT_R4 floating point number | Maximum volume - i.e. all segments are on. The maximum value that can be displayed in the indicator Default: 16
Decimals | VT_I2 short integer number | Number of the decimal signs after the "." used in the indicator labels Default: 1
Labels | VT_I4 integer number | Number of the lables displayed - 1. Indicator automatically displays text lables under the indocator bar. Default: 16
Marks | VT_I4 integer number | How many marks (vertical lines) to display under the indicator bar - 1. Usually number equal to the Steps value will do fine but if the steps are too much you can use Steps divided by 2 or 4 for better visual representation. Default: 16
Space | VT_I4 integer number | Space between components and control borders. Usally number between 1-4 will be good enough. Default: 2
CaptionLabel | BSTR string | Label displayed in the middle above the indicator bar. If empty label was removed and the other elments will grow to fill the space. Default: Volume indicator
border | VT_I2 short integer number | Border type of the indicator bar: 0 - none (not supported by the VolumeIndicator) 1 - sunken 2 - solid line (foreground color is used) Default: 2 (solid)
UseAmbientColors | VARIANT_BOOL boolean | If set to true ambient foreground and background colors are used instead of the colors specified through the BackColor and ForeColor properties. If the ambient color can not be obtained because of some reason own colors are used. Default: true
OnClick(volume) | (event) | Not very useful but supported. Fires when the user clicks over the indicator. volume parameter specifies the volume level corresponding to the click position calculated over the x coordinate of the mouse click and difference between the LabelEnd and LabelStart.


Volume Indicator control - sample
Use the buttons below to test the effect. Page source
This table has different color. Control picks its colors from the table cell

Volume=0

Indicator borders

Table cell background

UseAmbientColors

ForeColor (no effect in ambient mode)

BackColor (no effect in ambient mode)

Normal color "Light"

Caption

Text labels:


SimpleColorCheckBox control
Control supports IPersistPropertyBag and can be used in property bag enabled hosts.

Register the control's DLL and see the sample page.

Component class ID is: {5F16A989-CC61-4BA3-B893-77D85C1C65A4}
ProgID is: newObjects.ui.SimpleColorCheckBox

ColorOn | OLE_COLOR color | Color of the box for checked state Default: Light red
ColorOff | OLE_COLOR color | Color of the box for unchecked state Default: Dark red
ColorPress | OLE_COLOR color | Specifies the color used to indicate the focus (colored border drectangle). Default: Yellow
Checked | VARIANT_BOOL boolean | Read/write the check state for the color box Default: false (unchecked)
ui | VARIANT_BOOL boolean | If true box will automatically toggle its check state when clicked, if false will only fire the events - state changing can be made by the hosting code. OnClick and OnDblClick events are fired always. Default: true
ColorTextOn | OLE_COLOR color | Color of the text in the box in checked state Default: yellow
ColorTextOff | OLE_COLOR color | Color of the text in the box in unchecked state Default: Dark yellow
Text | BSTR string | Text in the box. It will be displayed centered in the current version Default: Click here
FixedFont | VARIANT_BOOL boolean | If true system fixed fonnt will be used, if false default dialog font will be used. Default: true
focusIndication | VARIANT_BOOL boolean | Enables disables the focus indication feature (see also ColorPress property). If set to false focus will not be indicated. Default: true
border | VT_I2 short integer number | Border type of the box: 0 - none 1 - sunken 2 - solid line (foreground color is used) Default: 1 (sunken)
OnClick(mouse_btn) | (event) | Fired when the user clicks with the left or right mouse button over the color box. Also fired when the control has keuboard focus and user clicks space bar or enter key. mouse_btn parameter is boolean value false for the left mouse button and kyboard input and true for the right mouse button
OnDblClick(mouse_btn) | (event) | Same as previous but fired on mouse doubleclick over the box. No keyboard input causes it.
OnChecked(check_state) | (event) | Fired when the check state changes. check_state is a boolean parameter that specifies the new state - true (checked), false (unchecked).


SimpleColorCheckBox - sample
Use the buttons below to test the effect. Page source
Test color boxes

Event=-

Check/uncheck

Caption of the Third

Enable/disable auto check on First

Enable/disable focus indication over First


Packet Object

Packet object is used by the USPC connections to represent the ACOM hardware protocol. Reference to such objects is passed to the extension method OnPacketReceived or otherwise is created by the extension (or core) and is passed to the ACOMTools.Transmit method.

All notifications from the ACOM hardware are received as Packet objects and all the commands to the same hardware are transmitted using the Packet object.

Program id: newObjects.USPC.ACOMSerialProtocolPacket

You can create a packet directly by using the object creation routine or by using the Core.Packet or Core.DefAmpPacket methods.

Direct creation sample:
VBS:
Dim p
Set p = ACOMTools.CreateObject("newObjects.USPC.ACOMSerialProtocolPacket")

Initially after its creation Packet object is marked as outgoing (see incomming property below). If you need to emulate because of some reason incoming packets set incomming property to true.

See also: ACOM serial protocol.

Properties

param(index)
Default, Indexed property. Sets/Gets a packet parameter. Packet parameter depends on the command and incomming property (incoming and outgoing commands are different sets of commands).
Few of the rarely used commands are not translated by the Packet object and can be manipulated only through the paramString property (see the command property for the list of commands)
index - is 0 based numeric index value. Count of the parameters for the command can be obtained from the paramCount property. Note that command property must be set for the outgoing packets in order to use param and paramCount properties.

packetType
Set/Get numeric type identificator of the packet type.

packetType | incoming | outgoing | Description
0 | yes | yes | Normal packets
1 | yes | yes (but not useful) | Forward power notification packet. Only volume property is meaningful. All other propertied must not be used.
2 | yes | yes (but not useful) | Reflected power notification packet. Only volume property is meaningful. All other propertied must not be used.
3 | no | yes | Custom command packet. Only command property is meaningful. It represents a custom command passed to the USPC driver. Command set depends on the USPC Driver.

rxType
First part of the address of the packet target unit (see comments section at the bottom of the page). This property sets/gets the type of the device.

rxGroup
Second part of the address of the packet target unit (see comments section at the bottom of the page). You can obtain the default group from the ACOMTools.Group property. If you want to target a device from another group you are responsible for choosing it (ACOMTools supports internally the default group and leaves other groups if they exist to the extensions).

txType
First part of the address of the packet transmitting (usually the PC if you are not going to simulate some other device) unit (see comments section at the bottom of the page). This property sets/gets the type of the device.

txGroup
Second part of the address of the packet transmitting unit (see comments section at the bottom of the page). You can obtain the default group from the ACOMTools.Group property. If you want to target a device from another group you are responsible for choosing it (ACOMTools supports internally the default group and leaves other groups if they exist to the extensions). In most cases the same PC group ID is used to communicate with any other group of devices but it is possible that an extension would want to talk to other groups simulating PC of their own group.

command
Set/get a string command that specifies the purpose of the packet. Incoming packets have this field already set by the protocol translator, for the outgoing packets it must be set before any usage of the param and paramCount properties. command property is meaningful if the packet type is 0 or 3. Packets of type 3 do not have parameters - all their parameters are coded in the command string (if there are parameters). After creation Packet type is 0 by default.

For the list of commands for normal packets see the ACOM serial protocol, for the custom commands (type 3) for the USPC drivers see the USPC dirver.

paramString
This property gives read/write access to the raw parameter data for the packet. It should not be used except for the packets whose parameters are not translated.

volume
Read/write the volume of the packets of type 1 and 2 (Forward and reflected power packets). For other packet types this property is not meaningful.

incomming
Set/get the type of the packet. If set to true packet is incoming (all the packets passed to the OnPacketReceived routines are incoming), if set to false it is outgouing packet (It is the default value set on object creation). By setting the property to true and passing the object to some other routine you can simulate some incoming packets that are not received in fact.

isBroadcast
Returns true if the packet is broadcasted to all the devices. Broadcast packets have rxType = 240 and rxGroup = 15. If you need to create broadcast packets use these values to address the target unit.

paramCount
Returns the allowed parameter count (use in conjunction with the param property). Available for packets of type 0 only (normal packets). The property has a meaningful value only of the command property is already set (it is set for the incoming packets by the translator).

Comments

Addressing: Packet objects (of type 0 only) contain unit addresses. One for the target unit (rx - prefix) and one for the transmitting unit (tx - prefix). There are sets of two properties for the both addresses in the Packet object - rxType,rxGroup for the target unit and txType,txGroup for the transmitting unit.

txType/rxType properties contain (set/get) the type constant for the units.
txGroup/rxGroup properties contain (set/get) the group ID of the units.

Types can be obtained from the ACOMTools.acomConstant property


ACOM serial protocol


SimpleColorCheckBox - sample
<html>

<head>
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<link REL="stylesheet" HREF="styles.css">
<title>SimpleColorCheckBox - sample</title>
<SCRIPT>
 var g_cnt = 0;
</SCRIPT>
<SCRIPT FOR="SimpleColorCheckBox2" EVENT="OnClick(b)">
    Evnt2.innerText = "Click over second box #" + (++g_cnt);
</SCRIPT>
</head>

<body bgcolor="#FFFFFF" topmargin="0" leftmargin="0">

<table border="0" width="100%" cellspacing="0" cellpadding="0" height="100%">
  <tr>
    <td width="100%" height="100%"><table border="0" width="100%" height="100%"
    cellspacing="0" cellpadding="4">
      <tr>
        <td width="100%" valign="top" align="left">
        Use the buttons below to test the effect. <a href="cbsamplesrc.htm"><b>Page
        source</b></a>&nbsp;
        <table border="0" bgcolor="#000000">
          <tr>
            <td width="100%" bgcolor="#D6DAE2">Test color boxes</td>
          </tr>
          <tr>
            <td width="100%" bgcolor="#D6DAE2" ID="cell1">
              <object classid="clsid:5F16A989-CC61-4BA3-B893-77D85C1C65A4" id="SimpleColorCheckBox1" width="103" height="23">
                <param name="Border" value="1">
                <param name="ColorOn" value="255">
                <param name="ColorOff" value="128">
                <param name="ColorPress" value="65535">
                <param name="Checked" value="0">
                <param name="ui" value="-1">
                <param name="ColorTextOn" value="65535">
                <param name="ColorTextOff" value="8421504">
                <param name="Text" value="First">
                <param name="FixedFont" value="-1">
              </object>
              &nbsp;
              <object classid="clsid:5F16A989-CC61-4BA3-B893-77D85C1C65A4" id="SimpleColorCheckBox2" width="103" height="23">
                <param name="Border" value="2">
                <param name="ColorOn" value="&HFF0000">
                <param name="ColorOff" value="&H800000">
                <param name="ColorPress" value="&H0000FF">
                <param name="Checked" value="0">
                <param name="ui" value="0">
                <param name="ColorTextOn" value="&HFFFFFF">
                <param name="ColorTextOff" value="&H808080">
                <param name="Text" value="Second">
                <param name="FixedFont" value="-1">
              </object>
              &nbsp;
              <object classid="clsid:5F16A989-CC61-4BA3-B893-77D85C1C65A4" id="SimpleColorCheckBox3" width="353" height="23">
                <param name="Border" value="0">
                <param name="ColorOn" value="&H00FFFF">
                <param name="ColorOff" value="&H00C0C0">
                <param name="ColorPress" value="&H00FF00">
                <param name="Checked" value="0">
                <param name="ui" value="1">
                <param name="ColorTextOn" value="&H000000">
                <param name="ColorTextOff" value="&H404040">
                <param name="Text" value="Third">
                <param name="FixedFont" value="0">
              </object>
              <BR>
              Event=<SPAN ID="Evnt2">-</SPAN>
            </td>
          </tr>
        </table>
        <p>
          Check/uncheck<br>
          <input type="button" value="Check second" onClick="SimpleColorCheckBox2.checked = true">
          <input type="button" value="Uncheck second" onClick="SimpleColorCheckBox2.checked = false">
        </p>
        <p>
          Caption of the Third<br>
          <input type="text" size="20" ID=indCapt>
          <input type="button" value="Set"
                  onClick="SimpleColorCheckBox3.Text = ((indCapt.value==null)?'':indCapt.value)">
        </p>

        <p>
          Enable/disable auto check on First<br>
          <input type="button" value="Enable" onClick="SimpleColorCheckBox1.ui = true">
          <input type="button" value="Disable" onClick="SimpleColorCheckBox1.ui = false">
        </p>

        <p>
          Enable/disable focus indication over First<br>
          <input type="button" value="Enable" onClick="SimpleColorCheckBox1.focusIndication = true">
          <input type="button" value="Disable" onClick="SimpleColorCheckBox1.focusIndication = false">
        </p>

        <p>
          &nbsp;
        </p>
        </td>
      </tr>
    </table>
    </td>
  </tr>
</table>
</body>
</html>


USPC Drivers


extensions collection object


Automation sample

var acom = new ActiveXObject("newObjects.automation.ACOMTools.API");
acom.extAdvisor.AmpPannel.alert("Hello!");
acom.extAdvisor.PlaySound(0);
acom.extAdvisor.AmpPannel("Status").Text = "This was set form the outside";

This sample creates ACOMToolsAPI object and shows alert, plays a sound and sets the status text of the AmpPannel object.


Volume Indicator control - sample source

Volume Indicator control - sample
<html>

<head>
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<link REL="stylesheet" HREF="styles.css">
<title>Volume Indicator control - sample</title>
<SCRIPT>
    var g_coef = 1;
    function randomVolume() {
        var dVol = Math.random() * 2 + 1;
        VolumeIndicatorCtl1.Volume += dVol*g_coef;
        if (VolumeIndicatorCtl1.Volume > VolumeIndicatorCtl1.LabelEnd) g_coef = -1;
        if (VolumeIndicatorCtl1.Volume < VolumeIndicatorCtl1.LabelStart) g_coef = 1;
        Volume.innerText = VolumeIndicatorCtl1.Volume;
    }
    function initPage() {
        setInterval("randomVolume()",20);
    }
</SCRIPT>
</head>

<body bgcolor="#FFFFFF" topmargin="0" leftmargin="0" onLoad="initPage()">

<table border="0" width="100%" cellspacing="0" cellpadding="0" height="100%">
   <tr>
    <td width="100%" height="100%"><table border="0" width="100%" height="100%"
    cellspacing="0" cellpadding="4">
      <tr>
        <td width="100%" valign="top" align="left">
        Use the buttons below to test the effect. <a href="visample.txt">Page
        source</a>&nbsp;
        <table border="0" bgcolor="#000000">
          <tr>
            <td width="100%" bgcolor="#D6DAE2">This table has different color.
              Control picks its colors from the table cell&nbsp;</td>
          </tr>
          <tr>
            <td width="100%" bgcolor="#D6DAE2" ID="cell1">
              <object classid="clsid:37A13A71-B41C-4B48-8A38-A12FA0447BE4" id="VolumeIndicatorCtl1" width="398" height="62">
                <param name="BackColor" value="16777215">
                <param name="ForeColor" value="0">
                <param name="NormalColor" value="32768">
                <param name="OverloadColor" value="128">
                <param name="NormalColorLight" value="65280">
                <param name="OverloadColorLight" value="255">
                <param name="Steps" value="32">
                <param name="StepsNormal" value="20">
                <param name="Volume" value="12.5">
                <param name="LabelStart" value="0">
                <param name="LabelEnd" value="32">
                <param name="Decimals" value="1">
                <param name="Labels" value="4">
                <param name="Marks" value="16">
                <param name="Space" value="2">
                <param name="CaptionLabel" value="Volume indicator">
                <param name="border" value="2">
                <param name="UseAmbientColors" value="1">
              </object>
              <BR>
              Volume=<SPAN ID="Volume">0</SPAN>
            </td>
          </tr>
        </table>
        <p>
          Indicator borders<br>
          <input type="button" value="Sunken border" onClick="VolumeIndicatorCtl1.border = 1">
          <input type="button" value="Solid border" onClick="VolumeIndicatorCtl1.border = 2">
        </p>
        <p>
          Table cell background<br>
          <input type="button" value="Gray" onClick="cell1.style.backgroundColor = 0xC0C0C0">
          <input type="button" value="Gray/blue" onClick="cell1.style.backgroundColor = 0xC0C0E0">
          <input type="button" value="Gray/green" onClick="cell1.style.backgroundColor = 0xC0E0C0">
        </p>
        <p>
          UseAmbientColors<br>
          <input type="button" value="UseAmbientColors = true" onClick="VolumeIndicatorCtl1.UseAmbientColors=true">
          <input type="button" value="UseAmbientColors = false" onClick="VolumeIndicatorCtl1.UseAmbientColors=false">
        </p>
        <p>
          ForeColor (no effect in ambient mode)<br>
          <input type="button" value="Black" onClick="VolumeIndicatorCtl1.ForeColor=0">
          <input type="button" value="Blue" onClick="VolumeIndicatorCtl1.ForeColor=0xFF0000">
          <input type="button" value="Red" onClick="VolumeIndicatorCtl1.ForeColor=0xFF">
          <input type="button" value="Green" onClick="VolumeIndicatorCtl1.ForeColor=0x00FF00">
        </p>
        <p>
          BackColor (no effect in ambient mode)<br>
          <input type="button" value="Black" onClick="VolumeIndicatorCtl1.BackColor=0">
          <input type="button" value="Blue" onClick="VolumeIndicatorCtl1.BackColor=0xFF0000">
          <input type="button" value="Red" onClick="VolumeIndicatorCtl1.BackColor=0xFF">
          <input type="button" value="Green" onClick="VolumeIndicatorCtl1.BackColor=0x00FF00">
        </p>
        <p>
          Normal color &quot;Light&quot;<br>
          <input type="button" value="Green" onClick="VolumeIndicatorCtl1.NormalColorLight=0xFF00">
          <input type="button" value="White" onClick="VolumeIndicatorCtl1.NormalColorLight=0xFFFFFF">
          <input type="button" value="Blue" onClick="VolumeIndicatorCtl1.NormalColorLight=0xFF0000">
        </p>
        <p>
          Caption<br>
          <input type="text" size="20" ID=indCapt>
          <input type="button" value="Set"
                  onClick="VolumeIndicatorCtl1.CaptionLabel = ((indCapt.value==null)?'':indCapt.value)">
        </p>
        <p>
          Text labels:
          <input type="button" value="4" onClick="VolumeIndicatorCtl1.Labels=4">
          <input type="button" value="6" onClick="VolumeIndicatorCtl1.Labels=6"><br>
        </p>
        <p>
          &nbsp;
        </p>
        </td>
      </tr>
    </table>
    </td>
  </tr>
</table>
</body>
</html>