Object-oriented tag browser6198480Abstract A system and method for displaying representations of tag sources representative of corresponding component devices is disclosed herein. The present system includes a tag dictionary for defining the tag sources in a predefined object-oriented format. The tag dictionary is comprised of tag definition objects, each containing information relating to a given tag source and each being associated with a tag type object. A tag browser allows for display and editing of the tag source representations in accordance with the tag definition objects. In a preferred implementation each of the representations includes information relating to a predefined set of parameters characterizing the tag sources. The tag browser also optionally includes a tag filter for causing display of those tag source representations comporting with tag selection criteria, and for suppressing display of all other tag source representations. A template tag dictionary is preferably provided within a development environment to facilitate generation of each tag dictionary. The template tag dictionary is modified within this development environment to reflect attributes of the tag sources. One or more template object-oriented controls of a predefined format compatible with the tag dictionary may also be provided in the development environment. These template object-oriented controls may be modified within the development environment so as to create a representation of each tag source of interest. Claims What is claimed is: Description FIELD OF THE INVENTION
GUID Globally Unique Identifier
CLSID COM coclass Identifier
IDL Interface Definition Language
ODL Object Description Language
BSTR A length prefixed, UNICODE (doublewide
byte) string.
OCX OLE Control (ActiveX Control)
LCID Local Identifier
ATL ActiveX Template Library
Coclass COM implementation class
PROGID Programmatic Identifier. A string that maps to a
CLSID.
Apartment An execution context for COM objects. Refer to
Microsoft Knowledge base article Q150777 for
more information on COM threading models.
Object Model Tag Dictionary COM Object Model Referring to FIG. 4, the Tag Dictionary Object represents a collection of Tag Definition Objects. The Tag Definition Object is has an associated Tag Type Object. The Tag Definition Object can also be a collection of other Tag Definition Objects if it is a tag collection (AKA Super Tags). The Tag Type Object is a collection of Dot Field Objects. Architecture FIG. 5 illustratively represents the relationship between the components of a tool kit including software components useful in realizing a preferred implementation of the present invention. The ClientPackage represents the client application associated with a particular container application. The ClientPackage will use the services of the TagDictionary Manager Package to select a particular tag dictionary and bind it to a tag source. The TagDictionary Manager Package also provides the services to initialize and invoke the Tag Browser. The initialization process is as follows: 1. The Client invokes the default Tag Dictionary binding it to the application's default tag source. 2. The Client invokes the Tag Browser (via the Tag Dictionary Manager Package) passing it default Tag dictionary and bound tag source and list of access names. 3. The user can pick tags and select other Tag Dictionary and associated tag sources via Tag Browser interface. Architecture FIG. 6 illustrates certain operations and data flow characterizing a preferred implementation of a Tag Browser of the present invention. How to Develop a Tag Provider Description The toolkit provides the capabilities to create a template Tag Provider. A Tag Provider consists of two modules, the Tag Dictionary (an in-process server COM object) and the Tag Dictionary's DataSource ActiveX control (Data Source Control). These components are split up like this to separate the user interface functionality (the ActiveX control) from the non-user interface model (the tag dictionary). The tag dictionary manager instantiates the ActiveX control to allow the user to locate the tag data source associated with the custom dictionary. Note that the developer is only responsible to create the control, register it, and provide the CLSID (via a method on the custom tag dictionary) so that the dictionary manager may instantiate the control within the context of the manager user interface. The developer is free to establish any proprietary communications (if required) between the custom tag dictionary and the custom ActiveX control. Important notes on the Tag Dictionary and it's DataSource Control Each tag dictionary must implement the ITagDictionary::GetDataSourceControClsid method that returns the CLSID of an ActiveX Control. This control must be capable of providing a user interface that allows selection of a data source for the tag dictionary. This control can be implemented in C, C++, Visual Basic, or any other language that supports COM interfaces. There are only a few requirements for implementing this control: The control must be 260-dialog units wide by 160-dialog units high (or 5850.times.3900 twips) assuming MS Sans Serif 8 point font. A required read/write property named "DataSource" of type BSTR. This property will be used to initialize the controls data source upon instantiation. The control container will use the optional DataSourceValidation (see below) method to determine if the DataSource property is valid. And if the property is valid, will read the property (and persist it). An optional method named "DataSourceValidation" with the following signature: ODL syntax: boolean DataSourceValidation([out]long* phWnd,[out] boolean* pBIsEdit) IDL syntax: HRESULT DataSourceValidation([out]long* phWnd, [out]VARIANT_BOOL* pBIsEdit, [out,retval] VARIANT_BOOL* pbResult); Where the return value is VARIANT_TRUE if the DataSource property is valid, VARIANT_FALSE otherwise. The phWnd (if non-NULL) indicates a valid HWND so that the control container may set focus and the boolean pBIsEdit indicates if this HWND is an EDIT control. If it is an EDIT control, the control container will set the selection property after setting focus. If this method is not provided by the control, the control container assumes that the control is always valid. If the validation fails, then the control has two options for allowing notification of the validation failure to be presented to the user. Either the control displays a message box or the control provides an optional read-only BSTR property called LastErrorDescription (It is suggested that the control use the latter method). Optional read-only property named "LastErrorDescription" of type BSTR. The control container, to determine the description of the validation failure (see DataSourceValidation), will query this property. This string should be a complete description of the reason for validation failure. Optional read-write property named "LocalID" of type long. This optional property will be used by the control container to specify the local identifier (LCID). The local identifier may affect the presentation of the control and the optional read-only LastErrorDescription property. Enumerations and Structures WWImageType enum typedef enum tagWWImageType
{
IMGTYPE_SMALL = 16,
IMGTYPE_BIG = 32
} WWImage Type
Description Used in the ITagDictionary::GetImageList method. Elements IMGTYPE_SMALL Request small images IMGTYPE_BIG Request large (or normal) size images WWFilterElement structure typedef struct tagWWFilterElement { DWORD UniqueID; LPOLESTR pFilterString; OLECHAR MultiChar; OLECHAR SingleChar; boolean bCaseSensitive; OLECHAR Placeholder; DWORD Reserved; } WWFilterElement; Description Used in the ITagDictionaryDelta::GetChangedIDs, ITagDictionaryDelta::GetNewIDs, ITagDictionary::GetTagIDs, and ITagDefinition::GetMemberTagIDs methods. Members
UniqueID The unique attribute identifier
pFilterString The filter string for this UniqueID
MultiChar The wildcard character used to specify multiple
characters
SingleChar The wildcard character used to specify a single character
bCaseSensitive Determines whether the given filter criteria should
be case sensitive.
TRUE==case sensitive, FALSE otherwise
Placeholder Determines which character within the
WWFilterSpecification's expression should be replaced
by the boolean value associated with this attribute and
filter string
Reserved This fleld is reserved for implementation details
WWResetDelta enum typedef enum tagWWResetDelta { RESET_NEW_IDS=1, RESET_DELETED_IDS, RESET_ALL_IDS } WWResetDelta Description Used in the ITagDictionaryDelta::ResetDelta method. Elements RESET_NEW_IDS Remove all new IDs from the collection RESET_CHANGED_IDS Remove all changed IDs from the collection RESET_DELETED_IDS Remove all deleted IDs from the collection RESET_ALL_IDS Remove all IDs from all of the delta collections (similar to calling ResetDelta three times with each of the enum values listed above). WWFilterSpecification structure typedef struct tagWWFilterSpecification { LPOLESTR pExpression; DWORD Count; WWFilterElement* pFilterElements; } WWFilterSpecification Description Used in the ITagDictionary::GetTagIDs, ITagDictionaryDelta::GetChangedIDs, ITagDictionaryDelta::GetNewIDs, and ITagDefinition::GetMemberTagIDs methods. Members
pExpression A boolean expression that describes the subset of IDs
to be retrieved. It consists of the operators
{&.vertline.!()} and
the characters {A..Z a..z}. For ease of integration
with the browser it is highly recommended that master
filters be restricted to {A..Z}.
Each character is replaced with the boolean value
generated by the WWFilterElement associated with it and
then the whole expression is evaluated to determine
whether or not the ID is to be included.
Count The number of WWFilterElements pointed to by
pFilterElements
pFilterElements A pointer to an array of Count many
WWFilterElement objects
WWAttributeID enum typedef enum tagWWAttributeID { ATTRIBID_FULLYQUALIFIED_NAME=0, ATTRIBID_HIERARCHICAL_NAME, ATTMIBID_TYPE, ATTRIBID_COMMENT, ATTRIBID_ALARM_GROUP, ATTRIBID_DDE_ACCESS_NAME, ATTRIBID_LOGGED, ATTRIBID_NESTED, ATTRIBID_EXPANDABLE, ATTRIBID_UDT_INSTANCE, ATTRIBID_MAX } WWAttributeID Description May be used with the ISpecifyTagAttributes::GetAttributes method (or any other method or structure that requires an attribute ID). Elements ATTRIBID_FULLYQUALIFIED_NAME The fully qualified name attribute. This is a required attribute and is represented by a LPOLESTR value. This attribute will have a display string. ATTRIBID_HIERARCHICAL_NAME The hierarchical name attribute. This is a required attribute and is represented by a LPOLESTR value. If no hierarchical name is available for the given attribute, then this ID should be mapped to ATTRIBID_FULLYQUALIFIED_NAME. This attribute will have a display string. ATTRIBID_TYPE Optional attribute ID for type. Its value is an LPOLESTR if this attribute is implemented. This attribute will have a display string. ATTRIBID_COMMENT Optional attribute ID for comments. Its value is an LPOLESTR if this attribute is implemented. This attribute will have a display string. ATTRIBID_ALARM_GROUP Optional attribute ID for alarm group. Its value is an LPOLESTR if this attribute is implemented. This attribute will have a display string. ATTRIBID_DDE_ACCESS_NAME Optional attribute ID for DDE access name. Its value is an LPOLESTR if this attribute is implemented. This attribute will have a display string. ATTRIBID_LOGGED Optional attribute ID for the logged command. Its value is an LPOLESTR that represents a Boolean ("1" or "0") if this attribute is implemented. This attribute does not have a display string. ATTRIBID_NESTED Required attribute ID for the nested command. Its value is an LPOLESTR that represents a Boolean ("1" or "0") if this attribute is implemented. This attribute does not have a display string. ATTRIBID_EXPANDABLE Required attribute ID for the expandable command. Its value is an LPOLESTR that represents a Boolean ("1" or "0") if this attribute is implemented. This attribute does not have a display string. ATTRIBID_UDT_INSTANCE Required attribute ID for a super tag. Its value is an LPOLESTR that represents a Boolean ("1" or "0") if this attribute is implemented. This attribute does not have a display string. ATTRIBID_MAX Represents the number of valid standard IDs. This is not a valid attribute identifier. WWExtendedAttribute structure typedef struct tagWWExtendedAttribute { LPOLESTR pAttribute; DWORD uniqueID; } WWExtendedAttribute; Description Used in the ISpecifyTagAttributes::GetAttributes method. Members
pAttribute If non-NULL represents attribute display string. If no display
string is available, then this element will be NULL
uniqueID The unique attribute identifiers.
ITagDictionaryManager Interface Defined in: TagIDL.h (TagIDL.IDL) Description Provides a method to retrieve an array of all tag dictionaries present on the local machine. Based On: IUnknown When to Use When it is desired to enumerate all of the tag dictionaries that have been installed on the local machine. Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
GetDictionaryNames Retrieves an array of strings. The strings are
formatted as a stringized GUID and a displayable
dictionary name.
ITagDictionaryManager:: GetDictionaryNames Method HRESULT GetDictionaryNames (LPOLESTR** dictionaryNames[], long* pCount) Description Retrieves an array of strings. Each string has the following format: "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}YYYYYYYY" Where the {xxxx . . . xxx} represents the CLSID of the tag dictionary coclass in Win32 registry standard form, and YYYYYYYY represents the display name of the tag dictionary. You are guaranteed that the GUID portion of the string is exactly 38 characters long. Parameters
DictionaryNames [out] upon success, the callee allocated array of strings
Pcount [out] a pointer to long what will hold the element
count (of strings in the array). This value may be zero,
indicating no strings were returned
Return Values
S_OK Returned one or more strings (*pCount>0)
S_FALSE No array elements were returned, *pCount = 0
E_OUTOFMEMORY Unable to allocate memory for returned array of
strings
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the
COM error object if available (see
ISupportErrorInfo and Error Objects)
Notes to Callers Each string in the array is allocated within the dictionary via CoTaskMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTasmMemFree (or IMalloc::Free). The outbound array is allocated within the dictionary via CoTaskMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree (or IMalloc::Free). Refer to the following examples. Notes to Implementers EXAMPLES Caller: long count=0; LPOLESTR* pStr=0; HRESULT hr=pTagDictionaryManager->GetDictionaryNames(&pStr,&count); for (long i=0; i<count; i++) { // operate on the returned string CoTaskMemFree(pStr[i]); } CoTaskMemFree(pStr); Implementor: const count=m_dictionaryNames.GetSize( ); if (count) { *pCount=count; //alloc up the array of string pointers LPOLESTR* pStrs=*pArray=static_cast<LPOLESTR*>( CoTaskMemAlloc(count * sizeof(LPOLESTR))); for (int i=0 ; i<count; i++) { pStrs[i]=ToWideStr::NewStr(m_dictionaryNames[i]); } ITagBrowserDig Interface Defined in: TagIDL.h (TagIDL.IDL) Description This is the primary interface of the browser user interface. The implementation of the Tag Browser provides the mechanism of tag selection from all Tag Dictionaries supporting the ITagDictionary interface. It provides methods to initialize the dialog by providing a filename, array of access names, and a primary filter. There is also a method to display the browser dialog along with parameters to allow customization of the user interface. Based On: IUnknown When to Use Use this interface to perform tag selection UI from InTouch. Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
Init Initializes the browser by giving an ITagDictionary
interface pointer and a base filter specification. Tag
Browser may cache tags at this point.
SetAccessNames Initialize the dialog with an array of access name
strings
DoTagPickerUI Invoke the dialog, hand it more initialization, and
returns values
ITagBrowserDlg::Init Method HRESULT Init (ITagDictionary* pTagDictionary, WWFilterSpecification* pFilter) Description Initializes the browser by giving an ITagDictionary interface pointer and a base filter specification. Tags may be cached into the tag browser at this point, so this may be an expensive call for larger tag dictionaries. Parameters
pTagDictionary [in] The primary interface pointer to a Tag Dictionary
object. The caller is responsible for instantiating a COM
object that supports this interface.
pFilter [in] The client may specify an array of attribute/filter
pairs with associated wildcard characters that will
act as a base filter for displaying tags. Tag
selection will be limited to those tags matching the filter
specification described by pFilter. This argument may be
NULL indicating no base filter should be applied.
Return Values
S_OK Initialization successfully completed
E_UNEXPECTED Initialization failed
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the COM
error object if available (see ISupportErrorInfo and
Error Objects)
Notes to Callers The Init method is used to set the set of tags that will be used by the browser. To facilitate faster display time when DoTagPickerUI is called, tags may be loaded into memory at time of the call to Init. Be aware that this can be a very time consuming operation (30 seconds / 32 k tags for InTouch), and may use a significant amount of memory (16 MB/32 k tags for InTouch) so this method should only be called when necessary (tag browser will eventually be displayed). Notes to Implementers N/A EXAMPLES The following example will initialize the tag browser with a base filter that will only include tags starting with the "$" character: ITagDictionary * pDictionary; ITagBrowserDlg * pDlg; (create dialog and dictionay, open dictionary) . . . WWFilterSpecification filterSpec; WWFilterElement filter; filter.UniqueID=ATTRIBID_HIERARCHICAL_NAME; filter.pFilterString=L"$*"; filter.MultiChar=`*`; filter.SingleChar=`.about.`; filter.bCaseSensitive=false; filter.Placeholder=`A`; filterSpec.pExpression=L"A"; filterSpec.Count=1; filterSpec.pFilterElements=&filter; HRESULT hr=pDlg->Init(pDict, &filterSpec); ITagBrowserDig:: SetAccessNames Method HRESULT SetAccessNames (long count, LPOLESTR accessNames[]) Description Allows the client of the browser dialog to specify an array of access name strings. It is expected that this method should be called prior to calling DoTagPickerUI. Parameters
count [in] Number access name strings held in the array
accessNames [in] An array of access name strings
Return Values
S_OK Upon successful completion.
E_UNEXPECTED Failure to initialize the access name array.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the COM
error object if available (see ISupportErrorInfo and
Error Objects)
Notes to Callers The access names provided with this call will be used to identify tag sources when the user creates them from within the tag browser. If no access names are supplied, the user is not allowed to create tag sources. Notes to Implementers N/A EXAMPLES The following example with set two access names, "Access1" and "Access2": LPOLESTR accessNames[2]; BSTR access1=SysAllocString(L"Access1"); BSTR access2=SysAllocString(L"Access2"); accessNames[0]=access1; accessNames[1]=access2; HRESULT hr=pDlg->SenccessNames(2,accessNames); SysFreeString(access1); SysFreeString(access2); ITagBrowserDlg::DoTagPickerUI Method HRESULT DoTagPickerUI (ITagDefinition** ppSelectedTag, IDotField** ppSelectedDotField, LPOLESTR* pSelectedTagAccessName, LPCOLESTR initialAccessName, LPCOLESTR initialTagName, LPCOLESTR initialDotField, boolean bAllowDictionarySelection, boolean bAllowDotFieldSelectioin, boolean bAllowExpandableTagSelection, boolean bAllowTreeNavigation, boolean bAllowNoneTagSelection, LPCOLESTR title, HWND parentHWND) Description Invokes the tag browser user interface dialog and provides output. Parameters
ppSelectedTag [out] interface pointer to the selected
tag
ppSelectedDotField [out] interface pointer to the selected
dot field
pSelectedTagAccessName [out] name string of the selected access
name
initialAccessName [in] used to initialize the dialog box (to
select initial access name)
initialTagName [in] used to initialize the dialog box (to
select initial tag name)
initialDotField [in] used to initialize the dialog box (to
select initial dot field)
bAllowDictionarySelection [in] TRUE to enable Tag Dictionary
selection UI, FALSE otherwise
bAllowDotFieldSelectioin [in] TRUE to enable dot field selection
UI, FALSE otherwise
bAllowExpandableTagSelection [in] TRUE to allow selection of
expandable tags (tags with children)
bAllowTreeNavigation [in] TRUE to allow user to navigate
tree.
bAllowNoneTagSelection [in] TRUE to allow user to select
<none> tag.
title [in] title string for the dialog box
(optional and may be NULL)
parentHWND [in] parent HWND (option and may
be NULL, if NULL then parent window
should be the desktop)
Return Values
S_OK Upon successful completion.
S_FALSE The user has press cancel, and all return values are
NULL
E_POINTER Upon detection of an invalid parameter (pointer)
E_UNEXPECTED Failure to invoke the picker user interface
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the COM
error object if available (see ISupportErrorInfo and
Error Objects)
Notes to Callers The input parameters may be NULL except if the initialDotFile is non-NULL, then the initialTagName must be non-NULL. If the user has canceled the dialog, then the returned interface pointers (ppSelectedTag, ppSelectedDotField) and selected tag access name (pSelectedTagAccessName) could be NULL and still return a success code (S_FALSE). EXAMPLES The following is a minimal example of displaying the tag browser dialog:
HRESULT TestTagPicker(ITagBrowserDlg* pDlg)
{
ITagDefinition* pTag = 0;
IDotField* pDot = 0;
WCHAR* pAccessName = 0;
HRBSULT hr = pDlg->DoTagPickerUI(&pTag
,&pDot
,&pAccessName
,0
,0
,0
,true
,true
,true
,true
,true
,0
,0);
if (SUCCEEDED(hr))
{
if (pTag)
ReleaseAndNull(pTag);
if (pDot)
ReleaseAndNull(pDot);
CoTaskMemFree(pAccessName);
}
return hr;
}
ISpecifyTagAttributes Interface Defined in: TagIDL.h (TagIDL.IDL) Description Provides a method to retrieve an array of all tag attributes that a tag dictionary has knowledge of. Based On: Iunknown When to Implement This is a required interface for the tag dictionary COM object. When to Use
Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
GetAttributes Retrieves an array of structures provides the set of
attributes (by unique identifiers and, if appropriate,
display strings).
SetLCID Allows setting the local identifier and, optionally,
retrieve the old local identifiers for a tag dictionary.
GetLCID Retrieves the currently installed local identifier for the
tag dictionary.
ISpecifyTagAttributes::GetAttributes Method HRESULT GetAttributes (WWExtendedAttributes** pArray, DWORD* pCount) Description Retrieves the entire set of attributes understood by the tag dictionary. Parameters
pArray [out] upon success, will return a callee allocated array of
structures. Refer to WWExtendedAttributes
pCount [out] the number of string elements (this value might be zero)
Return Values
S_OK Indicates success (with at one or more returned
structs, i.e., *pCount>0).
S_FALSE Indicates success (with no returned structs, i.e.,
*pCount==0)
E_UNEXPECTED A data source in not open. You must first call the
Open method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the
COM error object if available (see
ISupportErrorInfo and Error Objects)
E_OUTOFMEMORY Implementation cannot allocate enough memory
for the array of strings.
Notes to Callers The attribute structs obtained from this method represent the set of filterable values. Each string in the array is allocated within the dictionary via CoTaskMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTasmMemFree (or IMalloc::Free). The outbound array is allocated within the dictionary via CoTaskMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree (or IMalloc::Free). Refer to the following examples. Notes to Implementers The InTouch Tag Dictionary currently implements the following access names: "Fully Qualified Name" "Hierarchical Name" "Type" "Comment" "Alarm Group" "DDE Access Name" The first two attributes are required. It is suggested (but not required) that you provide the rest of these displayable attributes. In addition to these displayable attributes, there are some non-displayable attributes: LOGGED NESTED EXPANDABLE These non-displayable attributes represent Boolean values. The value strings associated with these are "1" for true and "0" for false. The NESTED and EXPANDABLE attributes are required. The LOGGED attribute is optional. Tag Dictionary implementers may add additional attributes, but the existing filtering mechanism will not provide a means to filter them. EXAMPLES ISpecifyTagAttributes::SetLCID Method HRESULT SetLCID (LCID localID, LCID* pOldlocalID) Description Allows the caller to specify a new local identifier so that returned display strings from the tag dictionary (via ITagDefinition::GetAttributeValue and the GetAttributes methods) will return localized strings. The default local ID is US English (LCID == 0.times.409). Parameters
localID [in] specifies a new local identifier.
pOldlocalID [out] the previous local identifier. This parameter is
optional and may be NULL
Return Values
S_OK Indicates success (the new local has been accepted).
S_FALSE Indicates failure to accept (the tag dictionary does not
support this local id)
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the COM error
object if available (see ISupportErrorInfo and Error Objects)
Notes to Implementers All string resources must be converted to the local specified if S_OK is returned. EXAMPLES ISpecifyTagAttributes::GetLCID Method HRESULT GetLCID (LCID* plocalID) Description Allows the caller to retrieve the currently installed local identifer. The default local is U.S. English (LCID == 0x409). Parameters plocalID [out] the currently installed LCID for the tag dictionary Return Values
S_OK Indicates success (the new local has been accepted).
E_POINTER Invalid pointer parameter.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the COM
error object if available (see ISupportErrorInfo and
Error Objects)
ITagDictionary Interface Defined in: TagIDL.h (TagIDL.IDL) Description This is the default tag dictionary interface. All tag dictionaries must support this, though they may derive from this interface in support of custom methods. Based On: IUnknown When to Implement This is a required interface for all tag dictionaries. Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
Open Initializes the dictionary COM object by
giving it a data source string
Close Requests that the dictionary close
connections to its data source
GetDisplayName Called by a UI component to get a string that
will be displayed to the user of this tag
dictionary implementation.
GetDataSourceControlClsid Called by a UI component to get the CLSID
of an ActiveX control that can be used to
find one of the dictionary's data sources.
GetImageList Called by a UI component to retrieve an
ImageList control. This image list should
contain bitmaps or icons that will be
displayed to the user. These images are used
for the dictionary object itself and all of the
tags that this dictionary implementation
supports.
GetImageIndex Called by the UI component to retrieve the
default index (into the ImageList, see
GetImageList method), and the optional
selected index for the bitmap or icon for
this dictionary implementation. To find the
image index for a tag, refer to
ITagType::GetImageIndex.
GetTagFromID Given a unique tag identifier, will answer
with an ITagDefintion pointer.
GetTagTypeEnum Supplies a pointer to an enumerator that can
enumerate the dictionary tag types
GetTagIDs Retrieves an array of unique tag identifiers.
The returned set of identifiers may be
effected by the filter parameter.
ITagDictionary::Open Method HRESULT Open (LPCOLESTR pDataSource) Description Initializes the dictionary COM object by giving it a data source string. Parameters pDataSource [in] a NULL terminated Unicode character string specifying the location of the dictionary's data source. The format and/or structure of this string may be unique for each dictionary implementation. Return Values
S_OK Indicates success.
E_UNEXPECTED A data source is already open, you must first call
Close.
E_FAIL Indicates failure to locate or open the data source.
Additional descriptive information can be obtained
by accessing the COM error object if available (see
ISupportErrorlnfo and Error Objects)
Notes to Callers This method must be called prior to calling the following methods: GetTagFromID, GetTagTypeEnum, GetAttributes, ITagDictionaryDelta:GetChangedTags, ITagDictionaryDelta:GetNewTags, ITagDictionaryDelta:GetDeletedTags, and GetTagIDs. EXAMPLES STDMETHODIMP CTD::Open( LPCOLESTR name) { AFX_MANAGE_STATE(AfxGetStaticModuleState( ) ) USES_CONVERSION; if (m_hFile !=INVALID_HANDLE_VALUE) return E_UNEXPECTED; m_hFile=CreateFile( W2T(name), GENERIC_READ, 0,0,OPEN_ALWAYS,FILE_ATTRIBUTE_NORMAL,0); return (m_hFile == INVALID_HANDLE_VALUE) ? E_FAIL:S_OK; } ITagDictionary::Close Method HRESULT Close ( ) Description Request that the tag dictionary close the connection to its data source. Parameters None Return Values
S_OK Indicates success.
S_FALSE Indicates that there is no opened data source
E_FAIL Indicates an exception. Additional descriptive information can
be obtained by accessing the COM error object if available
(see ISupportErrorInfo and Error Objects)
EXAMPLES STDMETHODIMP CTD::Close ( ) { AFX_MANAGE_STATE(AfxGetStaticModuleState( ) ) if (m_hFile !=INVALID_HANDLE_VALUE) return S_FALSE; CloseHandle(m_hFile); m_hFile=INVALID_HANDLE_VALUE; return S_OK; } ITagDictionary::GetDisplayName Method HRESULT GetDisplayName (LPOLESTR* ppDisplayName) Description User interface clients will call this to obtain a string that is descriptive of this tag dictionary COM object. This string is displayed to the user. Parameters ppDisplayName [out] address of a valid LPOLESTR to retrieve the display name for this tag dictionary. This name will be shown to the user. Return Values
S_OK Indicates success.
E_POINTER Invalid pointer parameter
E_OUTOFMEMORY The dictionary is unable to allocate memory for
the display string
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the
COM error object if available (see
ISupportErrorInfo and Error Objects)
Notes to Callers The dictionary, via the shared memory allocator CoTasmMemAlloc (or IMalloc::Alloc), allocates the string. It is the responsibility of the caller to deallocate this memory using CoTaskMemFree (or IMalloc::Free). EXAMPLES Caller: LPOLESTR pname=0; HRESULT hr=pTagDictionary->GetDispalyName(&pname); if (SUCCEEDED(hr)) { //use the name here CoTaskMemFreepname); //make sure to free the memory } Implementor: STDMETHODIMP CTD:: GetDispalyName (LPOLESTR* ppName) { AFX_MANAGE_STATE( AfxGetStaticModuleState( ) ) if( !ppName) return E_POINTER; //allocate memory for output string *ppnaame=static_cast<LPOLESTR>( CoTaskMemAlloc( (wcslen(m_pName) +1) * sizeof(WCHAR))), if(!*ppName ) return E_OUTOFMEMORY; wcscpy(*ppName, m_pName); return S_OK; } ITagDictionary::GetDataSourceControlClsid Method HRESULT GetDataSourceControlClsid(GUID* pClsid) Description User interface clients will request the dictionary's UI component through this method. The dictionary will provide the CLSID of an ActiveX control that knows how to find one of the dictionary's data sources. Refer to the topic "Writing a Dictionary ActiveX Control" for more details. Parameters pClsid [out] a valid pointer to a CLSID. Return Values
S_OK Indicates success.
E_POINTER Invalid pointer parameter
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the COM
error object if available (see ISupportErrorInfo and Error
Objects)
Notes to Callers Use the provided CLSID to instantiate the dictionary's UI control to allow the user to navigate to one of the dictionary's data sources. Notes to Implementers You may use the OLE library API CLSIDFromProgID to convert a PROGID to CLSID if you wish, but do not return the HRESULT of this API call. Only return the HRESULTs defined above. EXAMPLES Two methods are presented. One uses a PROGID and the other uses the CLSID: STDMETHODIMP CTD::GetDataSourceControlClsid(GUID* pClsid) { AFX_MANAGE_STATE(AfxGetStaticModuleState( ) ) USES_CONVERSION; if( ! pClsid) return E_POINTER; *pClsid=CLSID_NULL; //init outbound param CString str; str.LoadString(IDS_CONTROL_PROGID); HRESULT hr=CLSIDFromProgID( T2W(str), pClsid); return SUCCEEDED(hr) ? S_OK:E_FAIL; } STDMETHODIMP CTD::GetDataSourceControlClsid(GUID* pClsid) { AFX_MANAGE_STATE(AfGetStaticModuleState( ) ) if ( ! pClsid ) return E_POINTER; *pClsid=CLSID_MySpecialControl; return S_OK, } ITagDictionary::GetImageList Method HRESULT GetImageList (WWImageType imgType, IStream* pStream) Description User interface clients will call this method to obtain an IMAGELIST control from the tag dictionary object. This IMAGELIST will contain bitmaps or icons that can be used to display to the user. Parameters
imgType [in] requested image size.
pStream [in] caller supplied IStream pointer (used to stream the
IMAGELIST control)
Return Values
S_OK Indicates success (returns the specified image size).
S_FALSE Indicates success (returns the default image size, not the
one requested)
E_POINTER Invalid pointer parameter
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the COM
error object if available (see ISupportErrorInfo and
Error Objects)
Notes to Callers You are responsible to creating an IStream. This may be done in-memory (see the examples below). Be sure to use IStream::Seek to reset the stream pointer to the beginning of the stream prior to reading it's output (via ImageList_Read). Ownership of this stream interface is not given to the tag dictionary by this call. Notes to Implementers You may use the IMAGELIST common control macros to create and manage the IMAGELIST via calls to ImageList_LoadBitnap( ) or ImageList_Create( ). If using ImageList_LoadBitmap, then you must specify the color used to indicate transparency. Use ImageList_Write to stream out the results to the caller. You are free to destroy the IMAGELIST control after the call to ImageList_Write. EXAMPLES Caller: IStream* pStream=0; HRESULT hr=CreateStreamOnHGlobal(0,TRUE,&pStream); if (SUCCEEDED(hr)) { hr=pTagDictionary->GetImageList(IMGTYPE_SMALL,pStream); if (SUCCEEDED(hr)) { //make sure to seek the stream to the beginning LARGE_INTEGER Lint; ZeroMemory(&Lint,sizeof(Lint)); pStream->Seek(Lint,0,0); HIMAGELIST hImg=ImageList_Read(pStream); //now you can attach the imagelist to CImageList . . . } pStream->Release( ); } Implementor: STDMETHODIMP CTD::GetImageList (WWImageType imgtype, IStream* pstream) { AFX_MANAGE_STATE(AfGetStaticModuleState( ) ) if (! pstream) return E_POINTER; HIMAGELIST hImg; if (imgType == IMGTYPE_SMALL) { HImg=ImageList_LoadBitmap(_Module.GetResourceInstance( ), MAKEINTRESOURCE(IDB_TAGSMALL), IMGTYPE_SMALL,0,RGB(255,255,255)); }else{ { //similar loading of large images } if (hImg) { hr=ImageList_Write(hImg,pStrean) ? S.sub.-- OK:E_FAIL; ImageList_Destroy(hImg); } return hr; } ITagDictionary::GetImageIndex Method HRESULT GetImageIndex (long* pdefImgIndx, long* pSelImgIndx) Description This will allow the caller to find the index into the IMAGELIST control (returned from the call to GetImageList) that identifies the image(s) for this tag dictionary. Parameters pDefImgIndx [out] the index into the IMAGELIST control provided through the GetImageList method. This is the default image for use in the user interface for this tag dictionary. pSelImgIndx [out] the optional selected image index (caller may pass a NULL). Return Values
S_OK Indicates success.
E_POINTER Invalid pDefImgIndx pointer passed to the method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the COM
error object if available (see ISupportErrorInfo and Error
Objects)
Notes to Implementers Make sure that you test pSelImgIndx for NULL prior to use. It is an optional parameter. EXAMPLES STDMETHODIMP CTD::GetImageIndex (long* pDefImgIndx, long* pSelImgIndx) { AFX_MANAGE_STATE(AfxGetStaticModuleState( ) ) if (! pDefImgIndx) return E_POINTER; *pDefImgIndx=22; //index for the bitmap representation of this object //this param is optional and might be NULL if (pSelImgIndx) *pselImgIndx=1; return S_OK; } ITagDictionary::GetTagFromID Method HRESULT GetTagFromID (DWORD id, ITagDefinition** ppTag) Description Used to retrieve an interface pointer to an object that implements an ITagDefinition interface given the tags unique identifier. Parameters
id [in] unique tag definition identifier.
ppTag [out] upon success will return a ITagDefinition interface pointer
Return Values
S_OK Indicates success.
E_UNEXPECTED A data source in not open. You must first call
the Open method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the
COM error object if available (see
ISupportErrorInfo and Error Objects)
WWTD_E_TAGID The unique tag identifier is invalid
Notes to Callers You are responsible for calling Release on the provided ITagDefintion pointer. Notes to Implementers Filtering (if any) should not effect this method. Return any ITagDefinition for a valid ID irrespective of an installed filter. EXAMPLES Caller: ITagDefnition* pTag=0; HRESULT hr=pTagDictionary->GetTagFromID(uniqueID, &pTag); if (SUCCEEDED(hr)) { //use the pTag pointer to manipulate the Tag COM object //be sure to call Release when done pTag->Release( ); } Implementor: ITagDictionary::GetTagTypeEnum Method HRESULT GetTagTypeEnum (IEnumTagTypes** ppEnum) Parameters ppEnum [out] upon success, will return a IEnumTagType interface pointer. Return Values
S_OK Indicates success.
E_UNEXPECTED A data source in not open. You must first call
the Open method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the COM
error object if available (see ISupportErrorInfo and
Error Objects)
Notes to Callers The enumerator should be considered a snapshot of the collection. You are responsible for calling Release on the provided IEnumTagType pointer. ITagDictionary::GetTagIDs Method HRESULT GetTagIDs(WWFilterSpecification* pFilter , DWORD** ppIDs, DWORD *pdwCount); Description Retrieves the set of unique tag identifiers. The pfilter parameter can limit the resultant set. Parameters
pFilter [in] a filter specification used to limit the resulting tag
identifiers.
ppIDs [out] upon success, will return a callee allocated array of
unique tag identifiers.
pdwCount [out] the number of tag identifiers.
Return Values
S_OK Indicates success (with at one or more returned IDs,
i.e., *pCount > 0).
S_FALSE Indicates success (but no returned IDs: *pCount == 0)
E_UNEXPECTED A data source is not open. You must first call the Open
method.
E_INVALIDARG Indicates that invalid arguments were used.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
E_OUTOFMEMORY Implementation cannot allocate enough memory for the
array of
DWORDs.
E_POINTER Invalid pointer passed to method.
Notes to Callers The outbound array of DWORDs is allocated within the dictionary via CoTaskMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree. ITagDictionaryDelta Interface Defined in: TagIDL.h (TagIDL.IDL) Description This is an optional tag dictionary interface. Tag dictionaries that wish to provide a client with a means to track incremental changes to tags should implement this interface. Based On: IUnknown When to Implement When the tag dictionary manages a large collection of tags then implementing this interface allows a client to optimally query the dictionary for delta changes. When to Use When any change is made to a tag dictionary tag collection, the client (say, the tag browser) is expected to refresh the entire collection of tags via a call to ITagDictionary::GetTagIDs followed by repeated calls to ITagDictionary::GetTagFromID to query the tag for changed information to display to the user. If the size of the tag collection were large, then it would be more efficient to query only for the delta tag changes by using this (ITagDictionaryDelta) interface. Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
ResetDelta Allows the caller to clear out any or all of the delta
collections
independent of retrieving the collection elements.
GetChangedIDs Retrieves an array of unique tag identifiers that represent
tags that have
changed since the last GetTagIDs has been called.
GetNewIDs Retrieves an array of unique tag identifiers that represent
tags that have
been created since the last GetTagIDs has been called. The
filter parameter
will effect the returned set of ids.
GetDeletedIDs Retrieves an array of unique tag identifiers that represent
tags that have
been deleted since the last GetTagIDs has been called. The
filter parameter
will not effect the returned set of ids.
ITagDictionaryDelta::ResetDelta Method HRESULT ResetDelta(WWResetDelta enumReset); Description Provides a method to allow the caller to clear out any or all of the delta collections without retrieving the collection elements. This is an optional method and my return E_NOTIMPL; Parameters enumReset [in] specifies which delta collection (or all collections) should be cleared (see WWResetDelta) Return Values
S_OK Indicates success.
E_NOTIMPL Indicates that this method has not been implemented by
the tag dictionary
ITagDictionaryDelta::GetChangedIDs Method HRESULT GetChangedIDs(long lFilterCount, WWFilterElementfilters[], WWFilterLogical enumLogical, boolean bReset, DWORD **ppIDs, long *plCount) Description Retrieves the set of unique tag identifiers that have changed since the last call to GetTagIDs or GetChangedIDs when called with bReset == TRUE. Parameters
lFilterCount [in] the number of WWFilterElements in the filter array
filters [in] array of filters (see WWFilterElement)
enumLogical [in] if FILTER_LOGICAL_NULL, then no filter is specified and
lCount
should be 0.
if FILTER_LOGICAL_AND then all filter elements are ANDed
together
for the query. if FILTER_LOGICAL_OR then all filter elements
are
ORed together for the query.
bReset TRUE if the collection is to be cleared, FALSE otherwise
ppIDs [out] upon success, will return a callee allocated array of
unique tag
identifiers.
plCount [out] the number of ids. This value might be zero.
Return Values
S_OK Indicates success (with at one or more returned IDs,
i.e., *pCount > 0).
S_FALSE Indicates success (with no returned IDs, i.e., *pCount
== 0)
E_INVALIDARG Indicates that invalid arguments were pasted. This will
occur if
enumLogical is set to FILTER_LOGICAL_NULL and
lFilterCount is
non-zero or if enumLogical is FILTER_LOGICAL_AND or
FILTER_LOGICAL_OR and lFilterCount is zero.
E_UNEXPECTED A data source in not open. You must first call the Open
method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
E_OUTOFMEMORY Implementation cannot allocate enough memory for the
array of
DWORDs.
E_POINTER Invalid pointer passed to method.
Notes to Callers The outbound array of DWORDs is allocated within the dictionary via CoTaskMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree (or IMalloc::Free). Notes to Implementers When the clients call this method, you are then required to "flush" the corresponding collection so that subsequent calls will not hand out the same IDs if the caller has specified bReset == TRUE. ITagDictionaryDelta::GetNewIDs Method HRESULT GetNewIDs(long lFilterCount, WWFilterElement filters[], WWFilterLogical enumLogical, boolean bReset, DWORD** ppIDs, long *plCount); Description Retrieves the set of unique tag identifiers that have been created since the last call to GetTagIDs or GetNewIDs when called with bReset == TRUE. The filters array effects the TagIDs returned by this method. Parameters
lFilterCount [in] the number of WWFilterElements in the filter array
filters [in] array of filters (see WWFilterElement)
enumLogical [in] if FILTER_LOGICAL_NULL, then no filter is specified and
lFilterCount should be 0.
if FILTER_LOGICAL_AND then all filter elements are ANDed
together
for the query. if FILTER_LOGICAL_OR then all filter elements
are
ORed together for the query.
bReset [in] TRUE if the collection is to be cleared; FALSE otherwise
ppIDs [out] upon success, will return a callee allocated array of
unique tag
identifiers.
plCount [out] the number of ids.
Return Values
S_OK Indicates success (with at one or more returned IDs,
i.e., *pCount > 0).
S_FALSE Indicates success (with no returned IDs, i.e., *pCount
== 0)
E_INVALIDARG Indicates that invalid arguments were pasted. This will
occur if
enumLogical is set to FILTER_LOGICAL_NULL and
lFilterCount is
non-zero or if enumLogical is FILTBR_LOGICAL_AND or
FILTER_LOGICAL_OR and lFilterCount is zero.
E_UNEXPECTED A data source in not open. You must first call the Open
method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
E_OUTOFMEMORY Implementation cannot allocate enough memory for the
array of
DWORDs.
E_POINTER Invalid pointer passed to method.
Notes to Callers The outbound array of DWORDs is allocated within the dictionary via CoTaskMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree (or IMalloc::Free). Notes to Implementers You are responsible to "flush" your collection of IDs so that subsequent calls to this method do not return the same ID set if the caller has specified bReset == TRUE. ITagDictionaryDelta::GetDeletedTags Method HRESULT GetDeletedIDs (boolean bReset, DWORD** ppIDs, long* pCount); Description Retrieves the set of unique tag identifiers that have been deleted since the last call to GetTagIDs or GetDeletedIDs when called with bReset == TRUE. Parameters
bReset [in] TRUE if the collection is to be cleared, FALSE otherwise
ppIDs [out] upon success, will return a callee allocated array of
unique tag
identifiers.
pCount [out] the number of ids.
Return Values
S_OK Indicates success (with at one or more returned IDs,
i.e., *pCount > 0).
S_FALSE Indicates success (with no returned IDs, i.e., *pCount
== 0)
E_UNEXPECTED A data source in not open. You must first call the Open
method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
E_OUTOFMEMORY Implementation cannot allocate enough memory for the
array of
DWORDs.
E_POINTER Invalid pointer passed to method.
Notes to Callers The returned tag identifiers are not necessarily filtered (see ITagDictionaryFilter). This means that the caller may be returned tag identifiers that may not be allowed by the filter criteria. The outbound array of DWORDs is allocated within the dictionary via CoTaskMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree. Notes to Implementers You are responsible to "flush" your collection of IDs so that subsequent calls to this method do not return the same ID set if the caller has specified bReset == TRUE. EXAMPLES ItagDefinition Interface Defined in: TagIDL.h (TagIDL.IDL) Description The primary interface on a tag object. Allows retrieval of attributes (such as the required attributes: hierarchical and the fuilly qualified name), tag type interface, unique identifier, and member tags if the given tag implementation is a group tag (AKA gang or User Defined Tag). Based On: IUnknown Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
GetMemberTags Retrieves an array of unique identifiers if this tag
object is a collection tag.
GetTagType Returns an ITagType interface for this tag
GetID Returns a unique identifier for this tag (unique within
the context of a
specific tag dictionary)
GetAttributeValue Returns the value string for a given attribute (see
ITagDictionary::GetAttritubes)
ITagDefinition::GetMemberTagIDs Method HRESULT GetMemberTagIDs(WWFilterSpecification* pFilter , DWORD** ppIDs, long* plCount); Description Returns a callee allocated array of unique tag identifiers if this tag object is a gang tag (i.e., has member tags). Parameters
pFilter [in] A filter specification used to limit the set of tag
identifiers returned
ppIDs [out] callee allocated array of DWORD (unique tag identifiers)
if return is S_OK
plCount [out] the number of elements in the array (0 if return is
S_FALSE).
Return Values
S_OK The array of DWORD has been successfully allocated and
filled with at
least one entry (*pCount > 0).
S_FALSE This tag is not a group tag and has no members (the
array is empty and
*pCount == 0)
E_INVALIDARG Indicates that invalid arguments were pasted. This will
occur if
enumLogical is set to FILTER_LOGICAL_NULL and lCount is
non-zero
or if enumLogical is FILTBR_LOGICAL_AND or
FILTER_LOGICAL_OR and lCount is zero.
E_OUTOFMEMORY The array could not be allocated
E_POINTER An invalid pointer parameter was passed into the method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
Notes to Callers The outbound array of DWORDs is allocated within the implementation of this method via CoTaskMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree. ITagDefinition::GetTagType Method HRESULT GetTagType (ITagType** ppTagType) Description Retrieves the ITagType interface pointer describing the type of this tag. Parameters ppTagType [out] on success, will return an interface pointer to ITagType Return Values
S_OK Successful return of an ITagType interface pointer
E_POINTER An invalid pointer parameter was passed into the method.
E_FAIL Indicates an exception. Additional descriptive information
can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
Notes to Callers You are responsible for calling Release on the returned interface pointer ITagDefinition:: GetID Method HRESULT GetID (DWORD* pID) Parameters pID [out] on success, will return a unique identifier for this Tag (unique in the context of this tag dictionary) Return Values
S_OK Successful return of a unique tag identifier
E_POINTER An invalid pointer parameter was passed into the method.
E_FAIL Indicates an exception. Additional descriptive information
can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
ITagDefinition::GetAttributeValue Method HRESULT GetAttributeValue (DWORD AttribID), LPOLESTR* ppAttribValue) Description Returns the value string for a given attribute (see ITagDictionary::GetAttritubes). There are a set of standard attributes (some are optional and some required). Refer to ISpecifyTagAttributes and the definition of WWExtendedAttribute structure. If the AttribID is not known or implemented by a particular tag object implementation, then the ppAttribValue pointer should point to a null string (""). Parameters
AttribID [in] the unique attribute identifier (see
ISpecifyTagAttributes::GetAttributes)
ppAttribValue [out] on success, the value string for the given attribute.
If the AttribID is not
known or implemented by this tag object, then an empty string
should be returned
(*ppAttribValue == " ")
Return Values
S_OK Successful return of a non empty value string
S_FALSE The AttribID was not recognized. An empty string is
returned.
E_POINTBR An invalid pointer parameter was passed into the method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
E_OUTOFMEMORY unable to allocate enough memory for the output string
Notes to Callers You are responsible for deallocating the memory for the returned string (ppAttribValue) using CoTaskMemFree (or IMalloc::free). Notes to Implementers Do not return a NULL pointer for ppAttrib Value if the AttribID is not recognized. Instead, return an empty string. IEnumTagTypes Interface Defined in: TagIDL.h (TagIDL.IDL) Description Allows you to enumerate the TagTypes provided by a given Tag Dictionary implementation. Based On: IUnknown Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
Next Retrieves a specified number of ITagType interfaces in the
enumeration
sequence.
Skip Skips over a specified number of items in the enumeration
sequence.
Reset Resets the enumeration sequence to the beginning
Clone Creates another enumerator that contains the same enumeration
state as the current one.
IEnumTagTypes::Next Method HRESULT Next (ULONG cell, ITagType** rgelt, ULONG*pceltFetched) Description Retrieves the next celt items in the enumeration sequence. If there are less than the requested number of elements left in the sequence, it returns the remaining elements. The number of elements actually retrieved is returned through pceltFetched (unless the caller passed in NULL). Parameters
celt [in] Number of elements requested
rgelt [out] Array of size celt (or larger) of the elements of
interest.
pceltFetched [out] Pointer to the number of elements actually returned in
rgelt. Caller
may pass NULL if and only if celt is one.
Return Values
S_OK Indicates that celt elements have been found and returned.
S_FALSE Indicates the not all celt elements have been returned. Either
the caller
determines the number of elements from pceltFetched (if NULL was
not
passed) or if pceltFetched was set to NULL, then this indicates
that no
elements were returned.
E_FAIL Indicates an exception. Additional descriptive information can be
obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
Notes to Callers The caller is responsible for calling Release on all returned ITagType interface pointers. Note: the SUCCEEDED macro cannot be used to determine if you have reached the end of the enumeration sequence. S_FALSE is a success code! Notes to Implementers Be sure to AddRef all ITagType interface pointers handed out by this method call. IEnumTagTypes::Skip Method HRESULT Skip (ULONG celt) Description Skips over the next specified number of elements in the enumeration sequence. Parameters cell [in] Number of elements to be skipped Return Values
S_OK Indicates that celt elements have been skipped.
S_FALSE Indicates that the number of elements skipped is less than celt
E_FAIL Indicates an exception. Additional descriptive information can be
obtained by
accessing the COM error object if available (see
ISupportErrorInfo and Error
Objects)
Notes to Callers If S_FALSE is returned, then this indicates that you have skipped to the end of the enumeration. IEnumTagTypes::Reset Method HRESULT Reset () Description Resets the enumeration sequence to the beginning. Return Values
S_OK The enumeration has been reset.
E_FAIL Indicates an exception. Additional descriptive information can be
obtained by
accessing the COM error object if available (see
ISupportErrorInfo and Error
Objects)
IEnumTagTypes::Clone Method HRESULT Clone (IEnumTagTypes** ppEnum) Description Creates another enumerator that contains the same enumeration state as the current one. The new enumerator supports the same interface as the original one. Parameters ppEnum [out] if successful, an interface pointer to a new enumerator with the same state as the current one. Return Values
NOERROR if succeeded in producing the clone
E_POINTER if an invalid pointer is passed in as a parameter
E_OUTOFMEMORY if unable to allocate enough memory for the clone
E_FAIL Indicates an exception. Additional descriptive
information can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
Notes to Callers Using this method allows clients to record a cursor (with one enumerator) and continue to iterate through a collection (using another enumerator). Note that you are responsible for calling Release on the returned IEnumTagTypes interface pointer. Notes to Implementers You are responsible for calling AddRef on the IEnumTagTypes interface pointer you hand out. ITagType Interface Defined in: TagIDL.h (TagIDL.IDL) Description This is the primary interface on the Tag Type object. It provides the type name, a means to enumerate the dot fields, and indices into the IMAGELIST control returned by the ITagDictionary interface (see ITagDictionary::GetImageList). Based On: IUnknown Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
GetTypeName Retrieves the name string of the type instance
GetDotFieldEnum Retrieves a dot field enumerator allowing the caller to
iterate over the dot
fields
GetImageIndex Retrieves the default and optional selected index into the
IMAGELIST
control provided by the ITagDictionary interface.
ITagType::GetTypeName Method HRESULT GetTypeName (LPOLESTR* name) Description Returns the name of the tag type. Parameters name [out] callee allocated name string Return Values
S_OK Successful return of name string
E_OUTOFMEMORY The array could not be allocated
E_POINTER An invalid pointer parameter was passed into the method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error
Objects)
Notes to Callers The name string is allocated via the shared memory allocator CoTasmMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree (or IMalloc::Free). ITagType:: GetDotFieldEnum Method HRESULT GetDotFieldEnum (IEnumDotFields** ppEnum) Description Returns the dot field enumerator interface. Parameters ppEnum [out] interface pointer to a dot field enumerator. Return Values
S_OK Successful return of enumerator interface pointer
E_POINTER An invalid pointer parameter was passed into the method.
E_FAIL Indicates an exception. Additional descriptive information
can be obtained by
accessing the COM error object if available (see
ISupportErrorInfo and Error
Objects)
Notes to Callers You are responsible for calling Release on the provided IEnumDotFields pointer. ITagType::GetImageIndex Method HRESULT GetImagelndex (long* pDefImgIndx, long* pSelImgIndx) Description This will allow the caller to find the indices into the IMAGELIST control (returned from the call to ITagDictionary::GetImageList) that identifies the image(s) for this tag type. Parameters
pDefImgIndx [out] the index into the IMAGELIST control provided through
the
ITagDictionary::GetImageList method. This is the default
image for use in
the user interface for this tag type.
pSelImgIndx [out] the optional selected image index (may be NULL).
Return Values
S_OK Indicates success.
E_POINTER Invalid parameters pass to the method.
E_FAIL Indicates an exception. Additional descriptive information
can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
IEnumDotFields Interface Defined in: TagIDL.h (TagIDL.IDL) Description Allows you to enumerate the Dot Fields provided by a given Tag Dictionary implementation or Tag Definition. Based On: IUnknown Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
Next Retrieves a specified number of IDotField interfaces in the
enumeration
sequence.
Skip Skips over a specified number of items in the enumeration
sequence.
Reset Resets the enumeration sequence to the beginning
Clone Creates another enumerator that contains the same enumeration
state as
the current one.
IEnumDotFields::Next Method HRESULT Next (ULONG celt, IDotField** rgelt, ULONG* pceltFetched) Description Retrieves the next celt items in the enumeration sequence. If there are less than the requested number of elements left in the sequence, it returns the remaining elements. The number of elements actually retrieved is returned through pceltFetched (unless the caller passed in NULL). Parameters
celt [in] Number of elements requested
rgelt [out] Array of size celt (or larger) of the elements of
interest.
pCeltFetched [out] Pointer to the number of elements actually returned in
rgelt. Caller may pass
NULL if and only if celt is one.
Return Values
S_OK Indicates the celt elements have been found and returned.
S_FALSE Indicates the not all celt elements have been returned. Either
the caller determines
the number of elements from pceltFetched (if NULL was not passed)
or if
pceltFetched was
set to NULL, then this indicates that no elements were returned.
E_FAIL Indicates an exception. Additional descriptive information can be
obtained by
accessing the COM error object if available (see
ISupportErrorInfo and Error
Objects)
Notes to Callers The caller is responsible for calling Release on all returned IDotField interface pointers. Note: the SUCCEEDED macro cannot be used to determine if you have reached the end of the enumeration sequence. S_FALSE is a success code! Notes to Implementers Be sure to AddRef all IDotField interface pointers handed out by this method call. IEnumDotFields::Skip Method HRESULT Skip (ULONG celt) Description Skips over the next specified number of elements in the enumeration sequence. Parameters celt [in] Number of elements to be skipped Return Values
S_OK Indicates that celt elements have been skipped.
S_FALSE Indicates that the number of elements skipped is less than celt
E_FAIL Indicates an exception. Additional descriptive information can be
obtained by
accessing the COM error object if available (see
ISupportErrorInfo and Error
Objects)
Notes to Callers If S_FALSE is returned, then this indicates that you have skipped to the end of the enumeration. IEnumDotFields::Reset Method HRESULT Reset ( ) Description Resets the enumeration sequence to the beginning. Return Values
S_OK The enumeration has been reset.
E_FAIL Indicates an exception. Additional descriptive information can be
obtained by
accessing the COM error object if available (see
ISupportErrorInfo and Error
Objects)
IEnumDotFields::Clone Method HRESULT Clone (IEnumDotFields** ppEnum) Description Creates another enumerator that contains the same enumeration state as the current one. The new enumerator supports the same interface as the original one. Parameters ppEnum [out] if successful, an interface pointer to a new enumerator with the same state as the current one. Return Values
NOERROR if succeeded in producing the clone
E_POINTER if an invalid pointer is passed in as a parameter
E_OUTOFMEMORY if unable to allocate enough memory for the clone
E_FAIL Indicates an exception. Additional descriptive
information can be obtained
by accessing the COM error object if available (see
ISupportErrorInfo and
Error Objects)
Notes to Callers Using this method allows clients to record a cursor (with one enumerator) and continue to iterate through a collection (using another enumerator). Note that you are responsible for calling Release on the returned lEnumDotFields interface pointer. Notes to Implementers You are responsible for calling AddRef on the IEnuml)otFields interface pointer you hand out. EXAMPLES IDotField Interface Defined in: TagIDL.h (TagIDL.IDL) Description Provides the dot field name along with the name of its type. Based On: IUnknown Methods in Vtable Order
QueryInterface Standard IUnknown method
AddRef Standard IUnknown method
Release Standard IUnknown method
GetName Retrieves the name string of the dot field instance
GetTypeName Retrieves the type name.
IDotField::GetName Method HRESULT GetName (LPOLESTR* name) Description Returns the name of the dot field. Parameters name [out] callee allocated name string Return Values
S_OK Successful return of name string
E_OUTOFMEMORY The array could not be allocated
E_POINTER An invalid pointer parameter was passed into the
method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the
COM error object if available (see
ISupportErrorInfo and Error Objects)
Notes to Callers The name string is allocated via the shared memory allocator CoTasmMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree (or IMalloc::Free). IDotField::GetTypeName Method HRESULT GetTypeName (LPOLESTR* name) Description Returns the name of the dot field type. Parameters name [out] callee allocated name string Return Values
S_OK Successful return of name string
E_OUTOFMEMORY The array could not be allocated
E_POINTER An invalid pointer parameter was passed into the
method.
E_FAIL Indicates an exception. Additional descriptive
information can be obtained by accessing the
COM error object if available (see
ISupportErrorInfo and Error Objects)
Notes to Callers The name string is allocated via the shared memory allocator CoTasmMemAlloc (or IMalloc::Alloc). It is the responsibility of the caller to deallocate this memory using CoTaskMemFree (or IMalloc::Free). USE OF THE TAG BROWSER The Tag Browser provides a tool for viewing and selecting local and remote tagnames and tagname .fields from FactorySuite applications, or any other tag source that supports the InTouch Tagname Dictionary interface. It allows selection of existing tagnames, addition of new tagnames and viewing of basic Tagname Dictionary information. The Tag Browser may also be used to access the dialog boxes that allow you to perform tagname editing, replication, and to select tagnames (remote references) in remote tag sources. The first time the Tag Browser is accessed, <local> will be selected for the tag source by default. Meaning that the tagnames in the local application's Tagname Dictionary will be displayed. Thereafter, the last accessed tag source's tagnames will be displayed. The Tag Browser operates in two modes; "Filtered Selection Mode" and "Unlimited Selection Mode." The mode for the Tag Browser is determined by the method you use to access it. The following lists the primary methods that you can use to access the Tag Browser in each mode: Unlimited Selection Mode Double-clicking an animation link tagname or expression input box. Double-clicking an ActiveX or wizard tagname or expression input box. Double-clicking a blank area in any InTouch QuickScript window. In the InTouch QuickScript editor, selecting the Tagname command on the Insert menu. Pressing the ALT+N keys in the InTouch QuickScript editor. Double-clicking a blank New Name box in the Substitute Tagnames dialog box. Double-clicking the Tagname.FieldName input box in the SQL Access Bind List Configuration dialog box. Filtered Selection Mode Clicking the Select button in the Tagname Dictionary. When WindowMaker is running, double-clicking a cell in the Unit# column in a Recipe Manager Unit Template definition. In runtime, clicking any Pen# button in the Historical Trend Setup dialog box. In this instance, the Tag Browser will only display the tagnames that are defined with the Log Data option selected in the Tagname Dictionary. {character pullout} This functionality is only supported when the Alow Runtime Changes option has been selected for the historical trend during development. In runtime, clicking any object linked to the HTSelectTag() function. {character pullout} For more information on the Tag Browser modes, see "Tag Browser Selection Modes." The Tag Browser's status bar provides status on the following items for the currently displayed tag source: Total number of items in the application. The name of the currently selected item. Tagname field selected, if any. The Access Name associated with the tag source. Tag Browser Selection Modes The Tag Browser operates in two selection modes; Filtered Selection Mode and Unlimited Selection Mode. Filtered Selection Mode As shown in FIG. 7, If you click Select in the Tagname Dictionary dialog box or, during runtime (when the operator is allowed to make runtime changes to a historical trend) when selecting a new tagname for a historical trend pen, the tagnames displayed (and available for selecting) will be limited to the current InTouch application. For example, when you access the Tag Browser from the Tagname Dictionary and you select a tagname in this view, it's Tagname Dictionary definition appears after you click OK. Note Tagname .fields cannot be selected in this mode. Unlimited Selection Mode The unlimited selection mode is accessed by double-clicking in a blank area in any InTouch QuickScript window, animation link tagname or expression box or, a blank New Name box in the Substitute Tagnames dialog box. The tagnames defined in a local or remote tag source can be displayed and selected in this mode. Tagname .fields can also be selected for the tagname in this mode. When you select a tagname and/or tagname .field in this mode, it is automatically entered into the InTouch QuickScript, animation link tagname or expression box or, other location from which you accessed the Tag Browser. For example and with reference to FIG. 8: > To select a .field: 1. Click the Dot Field arrow to open the list of .fields that you can associate with the type of tagname currently selected. {character pullout} By default, <none> will initially be displayed for all types of tagnames. Note Dot Field is not available when you access the Tag Browser from the Tagname Dictionary or, during runtime, when selecting a tagname for a historical trend pen from the Historical Trend Setup dialog box. (The historical trend must be configured with the Allow runtime changes option selected.) 2. Click the .field in the list that you want to append to the selected tagname. {character pullout} Not every tagname type has the same .fields. For example, a Discrete type tagname has .OnMessage, whereas an analog does not. If you select a Discrete type tagname and you assign .OnMessage to it, and then you select another Discrete type tagname, the displayed .field list will not change. But, if you select another type of tagname in the control view list, for example an analog, the displayed .field will revert to <none>. Tag Browser Views The Tag Browser supports three control views; Tagname List Control, Tagname Details Control and Tagname Tree View Control. {character pullout} List View The list view is used to display and select tagnames within the current selection mode (described above). The Tagname List Control view displays the tagnames in two views depending upon the state of the List View and Details View buttons: When you select list view, small icons will be displayed next to the tagnames with icons displayed according to the type of each tagname. No other fields will be displayed in the list view. For example and with reference to FIG. 9: To refresh the display in the Select Tag dialog box, press F5. {character pullout} Details View When you select details view, the tagnames and their details are displayed in a multi-column format. The details displayed are Tagname Name, Tagname Type, Access Name, Alarm Group and Comment. You can sort the list by each detail type by clicking on its column header name. An item can be selected by clicking on any portion of its display, not just the tagname. (The entire row will be highlighted.). For example and with reference to FIG. 10: When you switch views, the selected tagname will remain visible and highlighted in the new view. {character pullout} Tree View The Tree View displays the tagnames in two views depending upon the state of the List View and Details View buttons. When you select the tree view, a pane appears on the left side of the dialog box. By using the Tree View you can also access the member tagnames in any SuperTag template. If the Details View mode is active when you select the Tree View, Tag Browser appears as indicated by FIG. 11. To expand a listing in the Tree View, double-click the application name or, click the +. To collapse a listing, double-click the application name again or, click the -. Double-clicking an application in the tree view pane is the same as selecting it in the Tag Source list. Note When you "drill down" through different levels in the Tag Browser, you can use the BACKSPACE key to "back up" to the previous level. Defining Tag Sources You must define the tag sources for viewing in the Tag Browser. The procedures for adding, deleting or editing tag sources are described in this section. When you add or edit a tag source definition, you will enter information such as the local network Access Name you want to associate with the tag source's tagnames, a user-defined application name, and the data source for the tag source. Note You will also use these procedures when you are converting placeholder tagnames to remote tagname references. {character pullout} For more information on remote tagname references, see "Converting Tagnames to Remote References." {character pullout} To define a tag source: 1. Open the Tag Browser, and then click the Define Tag Sources button. The Define Tag Sources dialog depicted in FIG. 12 will appear. Note If tag sources are already defined, they will be listed when the dialog box appears. The list will include the user-defined Name for the tag source, the Location of the tag source (path) and the local network Access Name associated with the application. {character pullout} To select multiple tag sources, hold down the SHIFT key as you click each name. To select multiple tag sources that are not consecutive in the list, hold down the CTRL key as you click each name. Note When the Define Tag Sources dialog box closes, you must click the Tag Source arrow in the Tag Browser and select the new tag source in the list. The Tag Browser is then refreshed and tagnames for the selected tag source are displayed. 3. To remove a tag source(s) from the Tag Source list in the Tag Browser, click the Define Tag Sources button. The Define Tag Sources dialog box appears. Select the tag source in the list, and then click Delete. 4. To edit a defined tag source, select it in the list, and then click Edit. The Define Tag Source dialog box appears displaying the configuration for the selected tag source. 5. To define a new tag source, click New. The Define Tag Source dialog 5 box of FIG. 13 appears. Note When you click New, if no Access Name is defined in your local application, a message box appears telling you there are no Access Names defined and you will not be allowed to define a new tag source. (Tag sources must be associated with a local network Access Name.) 6. In the Tag Source Name box, type a name to identify the tag source. 7. Click the Access Name arrow and select the Access Name in the local application that you want to associate with the tagnames in the tag source. 8. Click the Tag Source Type arrow and select the source for the tag source's tagname database. (By default, InTouch is displayed.) 9. The Location box displays the fill path to the tag source. 10. In the directory tree pane, locate the tag source, and then click OK. As is exemplified by FIG. 14, the Define Tag Sources dialog box reappears displaying the selected tag source: 11. Click Close. The Tag Browser reappears. 12. Click the {character pullout} tool to display the tree view pane to display all defined tag sources (see, e.g., the exemplary screen display of FIG. 15): If you are not using the tree view mode, click the Tag Source arrow and select the name for the tag source that you want to display in the list. The Tag Browser will refresh and the tag sources' tagnames will be displayed. The first time you access the Tag Browser, by default, <local> will be selected for the Tag Source. Thereafter, the tagnames for previously accessed tag source will be displayed. 13. Click OK. Defining Tag Browser Filters You will use the procedures described in this section to define the filters (search criteria) you want to use to populate the Tag Browser. By creating filters, you can sort any tagname list and display only the tagnames that meet the criteria you specify. You can sort the tagnames based on Tagname, Tag Type, Access Name, Alarm Groups and tagname Comments. You can use one or a combination of any of these items to set the criteria for your display. You can also save each filter instance and reuse it at any time. {character pullout} For example, if you have 40,000 tagnames defined in your Tagname Dictionary and you only need to deal with the 20 or so that are assigned to a particular Access Name or Alarm Group, you can create a filter and specify the Access Name and/or Alarm Group as the criteria that the tagnames must meet in order to be displayed in the Tag Browser. {character pullout} To define a search filter: 1. Click the Define Filter button. The Define Tag Filter dialog box depicted in FIG. 16 appears. If you right click the mouse in any of the text entry boxes, a menu appears displaying the commands that you can apply to the selected text. 2. In the Filter Name box, type a unique name to identify the filter that you are defining or, click the Filter Name arrow to select a previously defined filter name from the list. (As you define filters, the Filter Name you type is added to the list.) {character pullout} All of the Filter Option controls (Tagname, Tag Type, Access Name, Alarm Group and Comment) allow you to enter a wildcard expression to limit the scope of your search. If no filter is used, all of the tagnames in the currently displayed tag source will be displayed. The multiple wildcard is the asterisk (*). For example, "Asyn*" would search for all tagnames beginning with the character "Asyn". The single character wildcard is the tilde (?). For example, the filter, "Tag?" would search for all four character tagnames that begin with "Tag". The filter, "Tag??", would search for all five character tagnames that begin with "Tag", and so on. Any sequence of valid InTouch tagname characters, together with the two wildcard characters, is acceptable in a filter. The valid tagname characters are: A-Z, a-z, 0-9, !, @, -, ?, #, $, %, _, .backslash. and &. 3. In the Tagname box, type the tagname expression that you want to use as a filter. If left blank, the system will ignore this field in the filter definition. 4. In the Access Name box, type the local Access Name expression that you want to use as a filter. If left blank, the system will ignore this field in the filter definition. 5. In the Alarm Group box, type the name of the Alarm Group expression that you want to use as a filter. If left blank, the system will ignore this field in the filter definition. 6. In the Comment box, type the comment expression you want to use as a filter. If left blank, the system will ignore this field in the filter defintion. 7. Click OK to close dialog box. {character pullout} The Filter Name will now appear in the Filter list in the Tag Browser and you can select it to display only the tagnames meeting the criteria specified in the filter. > To delete a search filter: 1. Click the Filter arrow and select the filter name in the list that you want to delete. 2. Click Delete. The filter is immediately deleted. CROSS REFERENCE UTILITY The Tagname Cross Referencing utility allows you to determine your tagname, remote tagname and SuperTag usage in animation links, wizards, InTouch QuickScripts, QuickFunctions, ActiveX controls, scripts and the following InTouch add-on programs, SPC Pro, SQL Access Manager and Recipe Manager. For all objects such as wizards, ActiveX controls and animation links, it displays the window name and the coordinates of all objects linked to the tagname. It also allows you to view any QuickScript or QuickFunction where a tagname is found. {character pullout} For convenience, the Tagname Cross Reference utility can remain open in WindowMaker while you perform other tasks. > To use the InTouch Cross Reference utility: 1. On the Special menu, click Cross Reference or, in the Application Explorer double-click Cross Reference. The InTouch Cross Reference Search Criteria dialog box appears in the form depicted in FIG. 17. 2. The Search Criteria group allows you to limit the scope of your search. You can easily determine the scope by selecting only the options required. Search for all occurrences Search for all uses of the tagname or SuperTag in animation links, InTouch QuickScripts and all add-on programs such as SPC, SQL Access Manager, Recipe Manager, and so on. Search for specific occurrences Search for only the tagname or SuperTag only in the specified options . For example, if you only want to search for the usage in window scripts, only select Usage in window scripts. TAG BROWSER FUNCTIONALITY 1. Overview The Tag Browser presented here is designed to allow selection of tags from all supporting third party applications. 2. Dialogs 2.1 Tag Browser Referring to FIG. 18, the Tag Browser dialog is used for selecting tags and dot fields from FactorySuite applications, or any other tag source that supports the Tag Dictionary interfaces. 2.1.1 Modes 2.1.1.1 Limited Selection to Current Tag Source If the Tag Browser is launched from the InTouch Tag Dictionary dialog using the "Selec | ||||||