Download - TRIMSDK.pdf
Legal Notices
Warranty
The only warranties for HP products and services are set forth in the express warranty statementsaccompanying such products and services. Nothing herein should be construed as constituting an additionalwarranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
The information contained herein is subject to change without notice.
Restricted Rights Legend
Confidential computer software. Valid license from HP required for possession, use or copying. Consistentwith FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, andTechnical Data for Commercial Items are licensed to the U.S. Government under vendor's standardcommercial license.
Copyright Notices
© Copyright 2008-2009 Hewlett-Packard Development Company, L.P.
Outside In ® Viewer Technology Copyright © 1991, 2009 Oracle Corporation, Redwood City, California
Trademark Notices
Adobe® is a trademark of Adobe Systems Incorporated.
Intel®, Intel® Itanium®, Intel® Xeon™, and Pentium® are trademarks or registered trademarks of IntelCorporation or its subsidiaries in the United States and other countries.
Java™ is a U.S. trademark of Sun Microsystems, Inc.
Microsoft®, Windows®, and Windows® XP are U.S. registered trademarks of Microsoft Corporation.
Microsoft Vista® is either a registered trademark or trademark of Microsoft Corporation in the UnitedStates and/or other countries.
Oracle® is a registered U.S. trademark of Oracle Corporation, Redwood City, California.
UNIX® is a registered trademark of The Open Group.
Outside In ® is a registered trademark of Oracle Corporation, Redwood City, California
Documentation Updates
The title page of this document contains the following identifying information:
Software Version number, which indicates the software version.
Document Release Date, which changes each time the document is updated.
Software Release Date, which indicates the release date of this version of the software.
To check for recent updates or to verify that you are using the most recent edition of a document, go to:
http://h20230.www2.hp.com/selfsolve/manuals
This site requires that you register for an HP Passport and sign-in. To register for an HP Passport ID, go to:
http://h20229.www2.hp.com/passport-registration.html
Or click the New users - please register link on the HP Passport login page.
You will also receive updated or new editions if you subscribe to the appropriate product support service.Contact your HP sales representative for details.
Support
Visit the HP Software Support web site at:
http://www.hp.com/go/hpsoftwaresupport
This Web site provides contact information and details about the products, services, and support that HPSoftware offers.
HP Software online support provides customer self-solve capabilities. It provides a fast and efficient way toaccess interactive technical support tools needed to manage your business. As a valued support customer,you can benefit by using the support web site to:
Search for knowledge documents of interest
Submit and track support cases and enhancement requests
Download software patches
Manage support contracts
Look up HP support contacts
Review information about available services
Enter into discussions with other software customers
Research and register for software training
Most of the support areas require that you register as an HP Passport user and sign in. Many also require asupport contract. To register for an HP Passport ID, go to:
http://h20229.www2.hp.com/passport-registration.html
To find more information about access levels, go to:
http://h20230.www2.hp.com/new_access_levels.jsp
ContentsHP TRIM Software Development Kit ........................................................................................................... 8
Using the HP TRIM Software Development Kit........................................................................................ 8Technical Prerequisites and Assumptions .............................................................................................. 8
Using HP TRIM SDK with .NET Applications ................................................................................. 8A Short History of the SDK ................................................................................................................... 9What is the HP TRIM SDK? .................................................................................................................. 9
Better Building Blocks ......................................................................................................................10Hear, Say ...........................................................................................................................................10Taking Controls .................................................................................................................................10
The TRIM Object Model.......................................................................................................................11Objects and Interfaces .......................................................................................................................11Generic Interfaces..............................................................................................................................11
Base Objects ..................................................................................................................................11Child Objects .................................................................................................................................12Collections.....................................................................................................................................12Collections for Base and Child Objects.........................................................................................12
Methods and Properties .....................................................................................................................13Common Properties .......................................................................................................................13Common Methods .........................................................................................................................13Interactive Methods .......................................................................................................................14
Object Model Diagram ......................................................................................................................15Using the TRIM Object Model..............................................................................................................17
Database Object.................................................................................................................................17Working with Base Objects ...............................................................................................................17
Accessing Persistent Objects .........................................................................................................17Creating a New Object ..................................................................................................................18
Working With Collections of Base Objects.......................................................................................19Working With Child Objects .............................................................................................................20
Editing Child Objects ....................................................................................................................21Creating New Child Objects..........................................................................................................21Deleting Child Objects ..................................................................................................................22
Database Independent Objects...........................................................................................................22Object Properties ...............................................................................................................................24
Reading Properties.........................................................................................................................24Updating Properties .......................................................................................................................24User-Defined Properties ................................................................................................................25The PropertyDef object .................................................................................................................25The FieldDefinition Object............................................................................................................26
Acting on TRIM Events ........................................................................................................................26RecordAddIn .....................................................................................................................................27FieldAddIn.........................................................................................................................................29BaseObjectAddIn ..............................................................................................................................31EventProcessor ..................................................................................................................................33
ActiveX Controls...................................................................................................................................34Document Viewer - TRIMviewer......................................................................................................35Edit Box - TRIMedit..........................................................................................................................35Tree Box - TRIMtreeBox ..................................................................................................................37
Common Scenarios – Code Samples.....................................................................................................37Connecting to a Database ..................................................................................................................38
Connecting to a default database ...................................................................................................39Connecting to a specific database..................................................................................................40Allowing the user to choose a Database ........................................................................................41Code Example – C#......................................................................................................................41Showing and editing the properties of the TRIM Database object ................................................42
Accessing a Record ...........................................................................................................................45Getting a Record by Record Number ............................................................................................46Getting a Record by URI ...............................................................................................................47Reading Basic Properties...............................................................................................................48Accessing Related Objects ............................................................................................................49Accessing Record Location Information .......................................................................................50
Updating Records ..............................................................................................................................51Modifying Properties.....................................................................................................................52Calling Update Methods ................................................................................................................53Updating Properties Using SetProperty.........................................................................................54Verifying and Error Trapping........................................................................................................55Saving the Record to the Database ................................................................................................62
Searching for Records .......................................................................................................................63Creating a RecordSearch Object....................................................................................................64Adding a Search Clause.................................................................................................................65Boolean Operators - And, Or, Not.................................................................................................66User Selected Search Criteria ........................................................................................................67Applying Filters.............................................................................................................................68Sorting ...........................................................................................................................................69Displaying Results .........................................................................................................................70Processing Results Sequentially ....................................................................................................71Code Examples – Visual Basic.....................................................................................................72Code Examples – C# .....................................................................................................................75
Creating a Container File...................................................................................................................78Creating a Record of a given Type ................................................................................................79Controlled and Free Text Titling ...................................................................................................80Security Levels and Caveats..........................................................................................................81Access Control...............................................................................................................................82Relationships .................................................................................................................................84Record Locations...........................................................................................................................85Record Contacts.............................................................................................................................86Code Example - Visual Basic ........................................................................................................87Code Example - C#........................................................................................................................88
Creating a Document .........................................................................................................................89Titling and Numbering ..................................................................................................................90Assigning to a Container ...............................................................................................................91Attaching an Electronic Document................................................................................................92Document Author ..........................................................................................................................93Access Control for Documents......................................................................................................94Setting User-Defined Fields ..........................................................................................................95
Creating a Record with user input .....................................................................................................96Code Example – Visual Basic .......................................................................................................96Code Example – C#.......................................................................................................................97
Creating a Record with no user input ................................................................................................98Code Example – Visual Basic .......................................................................................................98Code Example – C#.......................................................................................................................99
Checking Out a Document ..............................................................................................................100Locating the Document ...............................................................................................................100Check Out Options ......................................................................................................................101Check In.......................................................................................................................................102
Working with Locations ..................................................................................................................103Finding a Person by Name...........................................................................................................103Creating a New Staff Member .....................................................................................................104
Reference.................................................................................................................................................107Objects.................................................................................................................................................107ActiveX Controls.................................................................................................................................107
Document Viewer - TRIMviewer....................................................................................................107Properties.....................................................................................................................................108Methods .......................................................................................................................................117Events ..........................................................................................................................................127
Edit Box - TRIMedit........................................................................................................................129Constituent Controls ....................................................................................................................132Property Pages .............................................................................................................................135Properties.....................................................................................................................................139Methods .......................................................................................................................................185Events ..........................................................................................................................................218
Tree Box - TRIMtreeBox ................................................................................................................231Sample Code................................................................................................................................232Properties.....................................................................................................................................245Methods .......................................................................................................................................274Events ..........................................................................................................................................306
Other Objects Used by the ActiveX Controls..................................................................................331TRIMdateTime ............................................................................................................................332TRIMfavorites .............................................................................................................................339TRIMtreeCol ...............................................................................................................................340TRIMtreeRow..............................................................................................................................358
Enumerated Types for ActiveX Controls ........................................................................................388dtCannedDate ..............................................................................................................................389fvFavoriteType ............................................................................................................................390ksBrowseMode ............................................................................................................................391ksCannedDatesMode ...................................................................................................................392ksEditValidMode.........................................................................................................................393ksScrollMode...............................................................................................................................394ksSelectMode ..............................................................................................................................395tbAlignmentMode........................................................................................................................396tbDisplayMode ............................................................................................................................397tbEllipsisMode.............................................................................................................................398ltbSortMode.................................................................................................................................399tbSortState ...................................................................................................................................400tbTagMode ..................................................................................................................................401tbVisibleMode .............................................................................................................................402TRIMIconId.................................................................................................................................403vwDocFormat ..............................................................................................................................412
Property Ids .........................................................................................................................................413What's New from TRIM Captura to the HP TRIM SDK.........................................................................414
Summary of Changes ..........................................................................................................................414Summary of New Features ..................................................................................................................417
New Objects ....................................................................................................................................417New Concepts..................................................................................................................................418
New Features In Detail ........................................................................................................................419Objects.............................................................................................................................................419Connecting to TRIM........................................................................................................................420Instantiating Objects ........................................................................................................................421Creating an Electronic Record.........................................................................................................422
HP TRIM 6 Software Development Kit
Page 8
HP TRIM Software Development KitThis document details the usage of the SDK components of HP TRIM.
Using the HP TRIM Software Development Kit
Introduction
This document describes the HP TRIM Software Development Kit (SDK). It providesan introduction to the design and content of the SDK, it gives instructions andguidance for using the various tools and objects, and is the logical starting point forthe SDK documentation suite.
For those wanting to understand the capabilities of the SDK, this document can beread on its own. For those intending to use the SDK it serves as an orientation andintroduction. For a complete technical understanding it is useful to view theTRIMSDK type library in the object browser of your chosen IDE, where you will finddetailed helpstrings for each object, method and property in the COM Interfaces ofthe SDK.
Effective integration of TRIM with other applications using the HP TRIM SDK requiresa technical understanding of the tools in the SDK, as well as a user perspective ofthe TRIM application in general and (most importantly) a business understanding ofthe particular implementation of TRIM and any other application for which anintegration is required.
Technical Prerequisites and Assumptions
The HP TRIM SDK components are based on Microsoft's Component Object Model(COM) standard. The SDK documentation assumes the reader is a programmer withan understanding of COM programming principles, the structure of COM-compliantobject models (i.e. objects, interfaces, methods and properties) and someexperience of using a COM-compliant programming language such as Visual Basic orC++. The code examples in the documentation are in Visual Basic as well as C#,although any COM-compliant language can be used with the SDK. The Visual Basicexamples are tested using the Visual Basic 6 compiler, while the C# examples aretested using Microsoft Visual Studio .NET 2003, requiring the .NET FrameworkVersion 1.1.
Using HP TRIM SDK with .NET Applications
The HP TRIM Primary Interop Assemblies are integral to the function of the HP TRIMSDK with .NET applications. These are distributed as .DLL files and contain the .NETequivalent of the Type Libraries of the HP TRIM SDK.
When developing a new application in .NET , the Assemblies may be referenced fromVisual Studio .NET through right-clicking on References in the Solution Explorer andbrowsing to select the necessary .DLL files.
HP TRIM 6 Software Development Kit
Page 9
A Short History of the SDK
In the early days of the TRIM Records & Document Management application (up toversion 4.1), it was generally not possible to programatically access the TRIMDatabase without resorting to writing SQL. This was no easy task. The programmerhad to fully understand the data schema and the complex data relationships totranslate a user's requirement into a set of SQL statements. It was even moredaunting if any data was to be modified, as it was necessary for the programmer tounderstand the application business rules to avoid corrupting the Database.
To help clients avoid these pitfalls, when version 4.2 of TRIM was released in 1997, itincluded an extra program that gave programmatic access to some of the internalapplication functionality through an small subset of functions labelled the TRIM API.By using this API instead of SQL to access the TRIM data, the business rules wereautomatically applied and therefore the Database integrity was preserved. The TRIM4.3 release expanded the capabilities of the API, exposing more of TRIM's underlyingfunctionality and thereby enabling a wide variety of integration possibilities withother applications. The business opportunities that this created has ensured that thisversion of the API has been widely used as a successful means of seamlesslyintegrating TRIM data and functionality into other applications. The TRIM 4.3 APIwas an out-of-process COM Automation server, implemented in a file called"tsapi.exe".
In the version 5.0 release of TRIM, the application has been given a major designoverhaul, creating a more robust, scalable enterprise architecture and a brand newlook-and-feel. As this was a "from-the-ground-up" redevelopment, the API wasreplaced by a comprehensive library of functions known as the SoftwareDevelopment Kit. For the first time, most of the TRIM business functions can beaccessed programatically. This gives the programmer vastly more control over theapplication and far greater scope for integration than was previously possible.
The new SDK COM interfaces (of which there are three) are in-process serversimplemented in DLLs.
What is the HP TRIM SDK?
The HP TRIM SDK is a suite of tools that allow programmers to create customsolutions, services and integrated applications by leveraging the functionality ofTRIM. These tools give TRIM clients and third-party integrators the opportunity toERDM-enable line-of-business applications, to create custom document-centricapplications, and to increase the return-on-investment of an organisation'sinformation assets, such as Classification systems, controlled vocabularies, andknowledge repositories.
The SDK is an in-process server implemented in a dynamic link library (dll) file. Thismethod of implementation means that the SDK is loaded into the same memoryspace as the application that invokes it. The result is fast execution of methods, andit also enables a number of separate applications to work with different Databasesthrough the same component.
At the core of the HP TRIM SDK is a comprehensive model of all business objects inHP TRIM. All data fields associated with these objects are exposed as propertiesthrough the SDK, and various methods are provided to implement commonapplication functionality. With very few exceptions, it is possible to programmaticallyaccess via the SDK all aspects of TRIM that are available through the client user
HP TRIM 6 Software Development Kit
Page 10
interface.
The security model is common to both the SDK and the TRIM client application –therefore any custom process that calls the SDK must connect to the Database usingthe current user's login, and this user's TRIM security profile determines the extentof data and functionality that the process can access.
In addition to the SDK exposing TRIM's data and functionality, TRIM 5 and 6 includessome other great features for the integration developer. These include ActiveXcontrols for bringing the rich experience of the TRIM User Interface into customapplications, and an event processor interface for responding to key events as theyoccur in TRIM.
Better Building Blocks
HP TRIM has been designed in such a way that all the business objects used in theapplication are automatically exposed through a thin COM wrapper createdautomatically during the application build process. This means that using the HPTRIM SDK is very efficient, and all the same underlying objects and properties thatthe application's programmers use to build the TRIM user interface are also availableto third-party programmers via the SDK.
Hear, Say
As an Automation server, the TRIM SDK defines the methods and properties that anAutomation client (a program or macro) can invoke. Another way of thinking of thisis that the SDK is the set of questions that TRIM can answer, and the commands thatit will obey.
The client and server relationship is sometimes called the master/slave relationship:the former does all the talking, and the latter does all the doing (and does not speakuntil spoken to).
The TRIM 5 and 6 SDK includes a feature that emancipates TRIM from this abjectslavery, and gives it the opportunity to speak for itself. The TRIMEventProcessor is aspecial class the TRIM Object Model. It is an outbound interface, meaning that TRIMcalls methods on this interface in response to events that occur in TRIM. Theintegration programmer can write code that implements these methods, andtherefore can execute code in a server process in response to actions in the TRIMclient.
Taking Controls
Another feature of the SDK that extends TRIM's integration options is the set ofActiveX controls. These are core elements of the TRIM application's user interfacethat can be built directly into another application's interface. The SDK includesmethods that allow the programmer to invoke certain TRIM dialogs with theappearance of being 'hosted' by another application, but the ActiveX controls takethe concept further, allowing edit controls, record lists and document viewers to bedirectly embedded inside custom dialogs and forms at design time.
HP TRIM 6 Software Development Kit
Page 11
The TRIM Object Model
Objects and Interfaces
To understand how objects in the HP TRIM SDK are used, you must have a basicunderstanding of objects and interfaces, and how they are used in the ComponentObject Model, otherwise known as COM. Interfaces are the key to understandingCOM, and directly affect the way COM objects in the SDK (and other COM-basedobject models) are used in code.
An object is an instance of a class, where a class is some common type of entity inan application. Typical classes of objects in the TRIM application are Records, RecordTypes and Locations. Each class of object has properties, which represent thenamed data attributes that are present on each instance of the class.
Generic Interfaces
In TRIM 4.3, all objects had a single interface, and all methods and properties thatthe object implemented were accessed through that interface. In the HP TRIM SDK,things are slightly different, as there are certain common interfaces that areimplemented by many different objects, in addition to the object's own defaultinterface. The benefit of this is that different types of objects can be treatedpolymorphically, using the common interface. It also allows extensibility of the SDK,such that new types of objects can be introduced in later versions, without breakingthe existing interface.
The common interfaces in the SDK are:
Interface Implemented By
IBaseObject Any objects that can be created anddeleted independently.
IBaseChildObject Any object that can only exist as a'child' of a Base object.
IBaseObjects Any collection of Base objects.
IBaseChildObjects Any collection of Base Child objects.
Which common interface is implemented depends on the type of object, i.e. whetherit is considered a Base Object or a Child Object (or a collection of either of the two.)
Base Objects
A Base Object is any first-order entity in the TRIM Database. It exists independentlyof other objects (although it may be related to many objects) and can be explicitlycreated or deleted by a user with the appropriate authority.
Examples of base objects are Records, Locations, Record Types, Keywords,Schedules, Document Stores, and many others.
Base Objects are also called 'persistent' objects because they persist after theprogram code that manipulates them is not executing (that is, the data for the object
HP TRIM 6 Software Development Kit
Page 12
can be saved in the TRIM Database and retrieved later to recreate the object).
All Base Objects have an internal Unique Row Identifier (URI) that uniquely identifiesdifferent objects of the same type, and most have a corresponding unique name orother identifier (such as Record Number) that is visible to the user. Whenever apersistent object is modified in the SDK, you must call a 'Save' method on the objectto commit the changes to the TRIM Database.
Child Objects
Child objects, on the other hand, only exist as a dependent of another object.
Examples of Child objects are Requests (children of a Record), Addresses (children ofa Location), and Lookup Items (children of a Lookup Set).
Generally speaking, child objects are created indirectly, as a result of performingsome task on a base object or a dependent collection object.
Some child objects represent a relationship between Base objects, such as RecordLocations, Record Keywords, and Related Records. Adding or removing child objectsdoes not directly affect the 'parent' Base objects (for example, the AttachedKeywordobject represents a Keyword (from the Thesaurus) associated with a particularRecord). Each instance of this object defines a relationship between a Record objectand a Keyword object, but if the AttachedKeyword instance is removed, the Recordand the Keyword objects themselves are unaffected.
Because of the dependence upon the parent object, child objects cannot beindependently saved, but the data they contain is persisted when the parent object issaved.
Collections
Collections are a special class of objects that are used to temporarily hold andmanipulate a set of several objects of the same type. They have a standardinterface that allows the programmer to access the items in the collection directly byindex position or to iterate through the collection sequentially. The standardconvention in the SDK is that a collection object takes the plural name of the type ofobject that it contains (for example, the Locations collection is used to hold multipleLocation objects).
If a given object implements the IBaseObject interface, then the Collection of thoseobjects will implement the IBaseObjects interface. Similarly, if a given objectimplements the IBaseChildObject interface, then the Collection of those objects willimplement the IBaseChildObjects interface.
Collections for Base and Child Objects
Dependent or Child objects are those that can be manipulated like other objects inthe SDK but which cannot be independently created or saved. These are usuallydependent upon one or more persistent objects in the Database, and often representrelationships rather than tangible objects. Typically, Child objects are held incollections that are accessed via a property of their parent object.
HP TRIM 6 Software Development Kit
Page 13
An example of a dependent collection is the AttachedKeywords collection. This canbe used like any other collection object to navigate to the keywords it contains.However, even though the collection can be modified (by adding or removingrelationships between keyword terms and the record), it is not independently saved.The information that the child collection represents is saved when the object onwhich it is dependent is saved. In the case of the AttachedKeywords example, therelationship between the record and the AttachedKeyword is saved in the Recordobject.
Methods and Properties
In the previous section we discussed the relationship between objects in the ObjectModel, and how objects implement predefined interfaces. Each interface is definedas a specific set of methods and properties, and it is through these that the objectprovides its functionality and data.
The definition of each method and property is provided in the reference section ofthis documentation. However, most object classes can be used according to genericprocesses, and these are discussed in the next sections on the Object Model.
Common Properties
Many objects in the TRIM 5 and 6 object model implement Properties with the samenames. This makes it easier for the programmer to learn the object model.Although not all objects implement these properties, the meaning is consistent forthose that do.
Property Description
Database Returns the Database object that created this object.
Uri Returns the internal number that uniquely identifies thisobject.
Verified Returns True if the current state of the object's data is valid.
Type Returns the object type for this object (for example, Record,Location etc.)
ErrorMessage Returns the description of the last error associated with thisobject.
Common Methods
As with common Properties, many objects implement Methods with the same (orsimilar) names.
Method Description
GetProperty Returns the data value of a property identified by a
HP TRIM 6 Software Development Kit
Page 14
property Id.
SetProperty Sets the data value of a property identified by a propertyId.
GetPropertiesAsString Returns the data values of a set of properties for theobject, as a string formatted for the use specified.
Verify Checks the validity of the current state of the object'sdata.
Save Saves the current state of the object to the TRIMDatabase
Delete Deletes the object from the TRIM Database.
Interactive Methods
Most methods in the TRIM 5 and 6 object model allow the programmer toautomatically perform some sort of data transformation in TRIM based on valuesprovided in code. The values may be determined at design-time, or they may bederived from the user at run-time through the custom application's user interface.However, sometimes the integrated application requires that the user interactsdirectly with one or more TRIM objects, and therefore requires a TRIM dialog to bedisplayed. The TRIM 5 and 6 object model exposes various methods that allow theprogrammer to invoke standard TRIM dialogs to be displayed to the user.
These interactive methods must only be called by code running on a clientworkstation, as most will invoke a modal dialog, which must be explicitly cleared bythe user before program execution can continue.
The interactive methods of an object are always identified by the suffix "UI" (for UserInterface) and will always take a ParentHWND parameter, which is a handle to thewindow object that will be the parent of the dialog. (Windows requires this to knowhow the dialog should behave when the user switches between running applications.)In the Visual Basic development environment, the global property hWnd will alwayscontain a handle to the current active window, and can therefore be used as theargument for the ParentHWND parameter. If the parent window handle is not ableto be determined, you can pass a "0" instead, in which case TRIM will place thedialog in front of the current foreground window of the current application. It is alsopossible to force a null parent for the dialog by passing a handle of "–1". This willforce the dialog to be a top level desktop window.
! Note: An alternative to calling interactive methods to achieve a TRIM 'look-and-feel' in an integrated application is to use the TRIM 5 and 6 ActiveX controlswithin the user interface of the application. This is described later in the TRIM 5and 6 ActiveX Controls section.
HP TRIM 6 Software Development Kit
Page 15
Object Model Diagram
GetRecordType
Database
Databases
Record
Records
RecordType
RecordTypes
InputDocument
EnumHelper
SignatureTool
TRIMEventProcessor
PropertyDef
PropertyDefs
SecurityLevel
SecurityLevels
SecurityCaveat
SecurityCaveats
SavedWorkflow
SavedWorkflows
ElectronicStore
ElectronicStores
RecordSearch
RecordSearches
Location
Locations
Space
Spaces
SavedActivity
SavedActivities
SavedTemplate
SavedTemplates
RecLocation
RecLocations
RecKeyword
RecKeywords
NewRecordType/s
GetRecord
NewRecord/s
GetRecordSearch
NewRecordSearch/es
GetRecordType
NewRecordType/s
GetLocation
NewLocation/s
GetSpace
NewSpace/s
GetSecurityLevel
NewSecurityLevel/s
GetSavedWorkflow
NewSavedWorkflow/s
GetSecurityCaveat
NewSecurityCaveat/s
GetSavedActivity
NewSavedActivity/ies
GetSavedTemplate
NewSavedTemplate/s
RecLinkedDocument
RecLinkedDocuments
RecRelationship
RecRelationships
RecRendition
RecRenditions
RecRevision
RecRevisions
RecRequest
RecRequests
LocEAddress
LocEAddresses
LocAddress
LocAddresses
LocEAddresses (prop.)
LocAddresses (prop.)
RecRevisions (prop.)
RecLocations (prop.)
RecKeywords (prop.)
RecLinkedDocuments (prop.)
RecRelated (prop.)
RecRenditions (prop.)
RecRequests (prop.)
See Next Page
Object
Collection
Legend
HP TRIM 6 Software Development Kit
Page 16
Classification
Classifications
Schedule
Schedules
Database
Databases
Keyword
Keywords
Report
Reports
LookupSet
LookupSets
LookupItem
LookupItems
ActionDef
ActionDefs
ActionName
ActionNames
Hold
Holds
HtmlLayout
HtmlLayouts
Stopword
Stopwords
ZipCode
ZipCodes
CdsLookupItems
GetKeyword
GetClassification
GetActionDef
FieldDef
FieldDefs
History
HistoryCollection
GetHistory
GetLookupSet
NewLookupSet/s
NewKeyword/s
NewSchedule/s
GetShedule
NewClassification/s
NewReport/s
GetReport
NewActionName/s
GetActionName
NewHtmlLayout/s
GetHtmlLayout
NewZipCode/s
GetZipCode
NewHistoryCollection
NewActionDef/s
GetHold
NewHold/s
GetStopword
NewStopword/s
GetFieldDef
NewFieldDef/s
See Previous Page
HP TRIM 6 Software Development Kit
Page 17
Using the TRIM Object Model
Database Object
The Database object is the top-level object in the TRIM object model hierarchy. It isgenerally the first object to be created when using the TRIM SDK.
Because most objects in TRIM can only exist in the context of a Database, theDatabase object is used for accessing and creating all other persistent businessobjects in the TRIM SDK. These objects are dependent upon the Database objectand cannot be created independently.
! Note: There are certain helper objects in the object model that do not need aDatabase, such as InputDocument, ExtractDocument, SignatureTool andEnumHelper.
Working with Base Objects
Accessing Persistent Objects
There are generally two ways to access existing persistent objects in the TRIMDatabase. The most reliable way is to use the object's URI, as this is guaranteed touniquely identify the object. The alternative is to use the object's Name – in mostcases this is also unique, but the name of an object can change after it is created,whereas the URI cannot.
The Database object has a number of methods for accessing different objects bytheir URI or Name, all taking the form:
Get<object> (LookForValue as Variant) As <object>
To instantiate an existing object, you must follow these steps:
Declare an object variable of the appropriate object type.
Determine the Name or URI of the object to be instantiated.
From a Database object, call the appropriate Get<object> method, passing the URIor Name as an argument to the method.
If the identifier is valid, the instantiated object will be returned by the method andassigned to the object variable.
Visual Basic Example
The following example code instantiates an existing record object with a Record Id of"RP95/1".
' Declare the object variableDim objRecord As TRIMSDK.RecordDim vntRecId As Variant
' Determine the identifiervntRecId = "RP95/1"
' Call Get… to instantiate the object
HP TRIM 6 Software Development Kit
Page 18
Set objRecord = objTRIM.GetRecord (vntRecId)
' Check that a record with this record number was foundIf objRecord Is Nothing Then
Msgbox "Record ID not found or not accessible due to security."End If
C# Example
The following example code instantiates an existing record object with a Record Id of"RP95/1".
// Determine the identifierstring vntRecId = "RP95/1";
// Call Get… to instantiate the objectTRIMSDK.Record objRecord = db.GetRecord(vntRecId);
// Check that a record with this record number was foundif (objRecord == null){
MessageBox.Show("Record ID not found or not accessible due to security.");}
Creating a New Object
All primary persistent objects can be created from the SDK via methods on theDatabase object. The format of these methods is "New<Objectname>".
A New<object> method returns a new instance of the specified object type. Thisobject contains only default information relating to the object type to begin with, andits properties must be set by code (or by interaction with the user.) Calling the"Save" method on the object commits the data to the Database.
The process for creating new objects is therefore as follows:
1. Define an object variable of the type <Object>.
2. On a Database object, call one of the NewObject methods. (The return value isthe new object.)
3. Set the properties of the <Object> variable, or call methods on it to set itsdata.
4. Call the Save method on the <Object> variable.
Visual Basic Example
The following example code creates a new Keyword (Thesaurus Tterm) object.' Declare the object variableDim objKeyword As TRIMSDK.Keyword
' Call New… to instantiate the objectSet objKeyword = objTRIM.NewKeyword
' Set propertiesobjKeyword.Name = "Example"objKeyword.TopTerm = True
' Save to the DatabaseobjKeyword.Save
C# Example
The following example code creates a new Keyword (Thesaurus Term) object.
HP TRIM 6 Software Development Kit
Page 19
// Declare the object variable and call New… to instantiate the objectTRIMSDK.Keyword objKeyword = db.NewKeyword();
// Set propertiesobjKeyword.Name = "Example";objKeyword.TopTerm = true;
// Save to the DatabaseobjKeyword.Save();
Working With Collections of Base Objects
Collections (of Base Objects) are used to manage related groups of objects of thesame type. Collections have several standard methods for iterating through theindividual objects, and most have additional methods for selecting objects to beincluded in the collection based on specific criteria.
When a collection is created it is always empty. You must call methods on thecollection to select object items to be included in the collection, based on criteriasuch as names or URIs. When the collection contains object items, you can callmethods that act upon the collection as a whole, such as displaying the collection tothe user, making a reference to the collection or printing the items in a Report.
The process for creating and working with collections is as follows:
1. Define an object variable of the type <Objects>.
2. On a Database object, call one of the "Make<Objects>" methods.
3. Add items to the collection using a "Select…" method, or allow the user tosearch for items using the RefineUI method (if implemented on this collectiontype).
4. Call methods to manipulate the collection as a group (see table below ofcommon collection methods), if required.
5. To access individual objects in the collection, call ChooseOneUI (userselection), Next (sequential access), or Item (indexed access). Each of thesewill return an instantiated object of the collection's type.
Visual Basic Example
The following example code allows the user to choose a single Record Type from allthe Record Types in the Database.
Dim colRecTypes As RecordTypesDim objRecType As RecordType
Set colRecTypes = objTRIM.MakeRecordTypesCall colRecTypes.SelectAllSet objRecType = colRecTypes.ChooseOneUI(hWnd)
C# Example
The following example code allows the user to choose a single Record Type from allthe Record Types in the Database.
TRIMSDK.RecordTypes colRecTypes = db.MakeRecordTypes();colRecTypes.SelectAll();int hWnd = Handle.ToInt32();TRIMSDK.RecordType objRecType = colRecTypes.ChooseOneUI(hWnd);
Method Description
HP TRIM 6 Software Development Kit
Page 20
SelectAll Fill the collection with all the objects of its type from theDatabase.
SelectByPrefix Add items to the collection by name prefix.
SelectByUris Add specific items to the collection. Takes an array ofobject URIs.
other "Select…"methods
Add items by other criteria. Different collection types willimplement different selectors.
RefineUI Allow the user to select items using a search dialog.
! Note: Not all collections provide this method.
Working With Child Objects
Child objects are dependents of base objects, and represent either sub-items of thebase object (for example, Addresses of a Location) or relationships with other baseobjects (for example, Keywords attached to a Record).
The only base objects in the TRIM Object Model that have Child objects are Records,Locations and LookupSets (see the Object Model diagram). The names of Recordchild objects are prefixed with "Rec", the names of Location child objects are prefixedwith "Loc", and the name of the LookupSet child objects are prefixed with "Cds".
The generic process for working with Child objects is slightly different to that forBase objects. Child objects always belong to a collection of "children" that is onlyable to be instantiated from the parent object. New child objects can be created bycalling the New method on the collection, and they can be deleted by calling theDelete method on the child object itself. Any changes to child objects (includingadditions and removals) are committed to the Database when the parent object issaved.
The process for instantiating a collection of child objects is as follows:
1. Define a collection object variable of the type <ChildObjects>.
2. Set the collection object variable to receive the value of the <ChildObjects>read-only property on an instantiated parent (Record, LookupSet or Location)object.
Visual Basic Example
The following example code instantiates the collection of Attached Keywords for theRecord "RP95/1", and displays them to the user.
Dim objRecord As RecordDim colKeywords As RecKeywords
Set objRecord = objTRIM.GetRecord("RP95/1")Set colKeywords = objRecord.RecKeywordsCall colKeywords.DisplayUI(hWnd)
C# Example
The following example code instantiates the collection of Attached Keywords for theRecord "RP95/1", and displays them to the user.
HP TRIM 6 Software Development Kit
Page 21
TRIMSDK.Record objRecord = db.GetRecord("RP95/1");TRIMSDK.RecKeywords colKeywords = objRecord.RecKeywords;int hWnd = Handle.ToInt32();colKeywords.DisplayUI(hWnd);
Editing Child Objects
The process for editing an existing child object is as follows:
1. Define an object variable of the type <ChildObject>
2. From an instantiated child collection, set the child object variable to receive thereturn value of the GetByUri method, the Item(n) read-only property or theChooseOne method.
3. Edit the properties of (and/or call methods on) the child object variable.
4. Save the parent object.
Visual Basic Example
The following example code modifies the contacts for the Record "G96/201",changing contacts of type 'Other' into type 'Addressee'.
Dim colContacts As RecLocationsDim objContact As RecLocation
Set objRecord = objTRIM.GetRecord("G96/201")Set colContacts = objRecord.RecLocationsFor i = 0 To colContacts.Count - 1 ' NB collections are zero-based
Set objContact = colContacts.Item(i)If objContact.RecLocType = rlContact _and objContact.Subtype = ctOther Then
objContact.Subtype = ctAddresseeEnd If
NextCall objRecord.Save
C# Example
The following example code modifies the contacts for the Record "G96/201",changing contacts of type 'Other' into type 'Addressee'.
TRIMSDK.Record objRecord = db.GetRecord("G96/201");TRIMSDK.RecLocations colContacts = objRecord.RecLocations;TRIMSDK.RecLocation objContact;for (int i = 0; i < colContacts.Count; i++)// NB collections are zero-based{
objContact = colContacts.Item(i);if ( objContact.RecLocType == rlRecordLocationType.rlContact
&& objContact.Subtype == ctContactType.ctOther){
objContact.Subtype = ctContactType.ctAddressee;}
}objRecord.Save();
Creating New Child Objects
Not all Child collections support creation of new objects. The RecRevisions collection,for example, cannot be explicitly added to because its members are only createdthrough the process of checking in a document as a new revision.
HP TRIM 6 Software Development Kit
Page 22
The process for creating a new child object is as follows:
1. Define an object variable of the type <ChildObject>
2. From an instantiated child collection, set the child object variable to receive thereturn value of the New method.
3. Edit the properties of (and/or call methods on) the child object variable.
4. Save the parent Record or Location.
! Note: however, that in most cases the Record object also provides 'shortcut'methods as an alternative means of creating new child objects, where theproperties of the child object are set through parameters on the method (forexample, the AttachRelationship method creates a new RecRelationship childobject).(See the table below for the shortcut methods exposed by the Record interface.)
Record Method Child Object Created
AttachContact RecLocation
AttachKeyword RecKeyword
AttachRelationship RecRelationship
MakeRequest RecRequest
Deleting Child Objects
Some child objects represent a sub-item of an object (such as a Location Address)that cannot exist independently of the parent, and deleting the child object thereforepermanently deletes the sub-item from the Database. However, when you delete achild object that represents a relationship between base items, you are only deletingthe relationship, not the item (for example, deleting the RecKeyword "MarineAnimals" from the RecKeywords collection belonging to Record "RP95/2" simplydetaches the keyword from the record).
The process for deleting a child object is as follows:
1. Define an object variable of the type <ChildObject>
2. From an instantiated child collection, set the child object variable to receive thereturn value of the GetByUri method, the Item(n) read-only property or theChooseOne method.
3. Call the Delete method on the child object variable.
4. Save the parent object.
Database Independent Objects
There are a number of objects in the object model that are not dependent on a
HP TRIM 6 Software Development Kit
Page 23
Database object to be used in the SDK. These objects are
InputDocument
ExtractDocument
SignatureTool
EnumHelper
The above of objects are not instantiated through the database object, with a‘Database.New<object>’ statement. They are simply instantiated on their own, as isany typical object in your IDE.
HP TRIM 6 Software Development Kit
Page 24
Object Properties
This section describes how an object's data is manipulated via properties andmethods.
Overview
The standard data properties of an object are explicitly exposed – that is, there is anamed property representing each predefined value of an object. These propertiesare strongly typed – meaning that each has a specific data type (for example, String,Boolean, Long Integer, Date) and the data variable used to set or get the propertyvalue must match that type. An object's properties can be accessed according to theconventions of the automation language you are using.
In Visual Basic (and most other automation languages), an object property isaccessed in the following way:strMyValue = objRecord.Title ' read the Title propertyobjRecord.Title = strMyValue ' update the Title property
(Some automation languages require property values to be accessed through specialmethods, in which the property name is prefixed with values such as 'get_' to readand 'put_' to update.)
It is also possible to manipulate object properties through generic methods, by usingTRIM's internal property identifiers to specify a property (see the Property Idssection), and a variant data type to hold the property's data value. This technique isdiscussed in the section on the PropertyDef object.
Reading Properties
You can read the value of an individual TRIM object property simply by accessing theproperty by name. Properties always have a specific data type, and therefore yourusage of the property should be consistent with the property type. A Record object'sTitle property, for example, is a String type, whereas the HomeLoc property returnsa Location object.
All Base and Child objects also expose a GetProperty method, and you can call thismethod to retrieve a property value as a Variant type. The method requires that youpass as a parameter the unique property identifier for the property you require.
Updating Properties
You can set or update the value of an object property by assigning a value of thecorrect data type directly to the property by name.
! Note: that some named object properties are read-only, and therefore cannotbe updated. The reference documentation and the object viewer indicate whichproperties are read-only.
Most objects also expose a SetProperty method, and you can call this method toupdate the property value by passing a new value argument as a Variant and theunique property identifier as an integer value.
HP TRIM 6 Software Development Kit
Page 25
User-Defined Properties
In HP TRIM, the system administrator can define any number of additional UserDefined Fields to be associated with TRIM records. The values of these User DefinedFields can be accessed and updated through the SDK by using the Record object'sGetUserField and SetUserField methods.
These methods pass field values as variant data types, and require a FieldDefinitionargument to specify the desired field. A FieldDefinition object can be instantiated (byname or Uri) using the GetFieldDefinition method on the Database object.
(See The FieldDefinition Object section.)
The PropertyDef object
Generic handling of properties of all TRIM objects is managed through thePropertyDef object and its associated PropertyDefs collection.
A PropertyDef object manages the unique identifier for an object's property, andprovides additional information about the format and structure of the property. Itdoes not, however, contain the data value of the property.
Individual PropertyDef objects are instantiated by specifying a unique internalproperty Id (see the section on Property Ids), or alternatively (and more easily) byiterating through an instantiated PropertyDefs collection. The collection isinstantiated by calling one of the 'Select…' methods exposed by the collection, eachof which takes an argument identifying a base object type (a member of thebtyBaseObjectTypes enumeration.) These methods add property definitions to thecollection for the specified object type, and provide options to select all properties forthe object type, all properties available to the View Pane (or those included on theview pane by default), all modifiable properties or all properties for a givensubgroup.
Visual Basic Example
This example demonstrates the use of a PropertyDefs collection, which is in this caseinstantiated using the method SelectViewPaneItems, passing the Record object typeidentifier. In a loop, a PropertyDef object is used to iterate the collection, and theprogram outputs each property's Caption and the string representation of its datavalue.
Private Sub PrintProperties(objRecord As Record)Dim objProp As New PropertyDefDim colProps As New PropertyDefs
Call colProps.SelectViewPaneItems(btyRecord)For i = 0 To colProps.Count - 1
Set objProp = colProps(i)Debug.Print objProp.GetCaption(objRecord.Database) & _" : " & objRecord.GetPropertyAsString(objProp)
NextEnd Sub
C# Example
This example demonstrates the use of a PropertyDefs collection, which is in this caseinstantiated using the method SelectViewPaneItems, passing the Record object typeidentifier. In a loop, a PropertyDef object is used to iterate the collection, and theprogram outputs each property's Caption and the string representation of its data
HP TRIM 6 Software Development Kit
Page 26
value.
private void PrintProperties(Record objRecord){
TRIMSDK.PropertyDef objProp = new TRIMSDK.PropertyDef();TRIMSDK.PropertyDefs colProps = new TRIMSDK.PropertyDefs();
// C# requires specification of default parameterscolProps.SelectViewPaneItems(btyBaseObjectTypes.btyRecord,false);for (int i = 0; i < colProps.Count; i++){
objProp = colProps[i];Console.WriteLine("{0}:{1}", objProp.GetCaption(objRecord.Database,
false), objRecord.GetPropertyAsString(objProp, sdStringDisplayType.sdDefault, false));}
}
The FieldDefinition Object
HP TRIM allows a large number of User Defined Fields to be assigned to records.Therefore User Defined Fields cannot be interrogated using normal named propertiesof the record object. Instead, accessing User Defined Fields is carried out using adedicated object for managing these fields, the FieldDefinition object, and itsassociated FieldDefinitions collection.
The Record object has a pair of methods for manipulating User Defined Fields,GetUserField and SetUserField. Each method takes a populated FieldDefinition objectas a parameter.
Acting on TRIM Events
There are a number of interfaces allowing the programmer to run custom code inresponse to events that occur in HP TRIM. They are:
RecordAddIn
FieldAddIn
BaseObjectAddIn (New in TRIM 6.1)
EventProcessor
HP TRIM 6 Software Development Kit
Page 27
RecordAddIn
The RecordAddIn gives access to generic entry points in various processes for theRecord. Methods, within which custom code may be placed, are shown below in blue.
Although the RecordAddIn class is defined in the TRIMSDK Type Library (along withall the other TRIM SDK object classes), it is a special class, in that it is only aninterface definition, and the programmer must implement the interface to act uponmethod calls made by TRIM. (All other classes in the Type Library representinterfaces implemented by TRIM, and the programmer can call the methods on theseinterfaces).
The ErrorMessage property of the FieldAddIn (not shown in the diagram below)provides some functionality for catching and displaying error messages to the user.If the PreSave or PreDelete return false, the ErrorMessage property will be called andpopulated with the corresponding error message. The SDK programmer may also callthe ErrorMessage property explicitly in code and populate it with a customized errormessage.
It should be noted that none of the methods of the RecordAddIn provide aParentHWnd parameter (a handle to the user’s current window). is not advisable touse dialogs in situations where no ParentHWnd parameter is provided, as without ahandle to the user’s window, the dialogs may be popping up on the server machinewith nobody to answer them.
HP TRIM 6 Software Development Kit
Page 29
FieldAddIn
The FieldAddIn provides access to generic entry points in processes involving UserField modification. Methods, within which custom code may be placed, are shownbelow in blue.
Although the FieldAddIn class is defined in the TRIMSDK Type Library (along with allthe other TRIM SDK object classes), it is a special class, in that it is only an interfacedefinition, and the programmer must implement the interface to act upon methodcalls made by TRIM. (All other classes in the Type Library represent interfacesimplemented by TRIM, and the programmer can call the methods on theseinterfaces).
The ErrorMessage property of the FieldAddIn (not shown in the diagram below)provides some functionality for catching and displaying error messages to the user.If the VerifyFieldValue method returns ‘false’, the ErrorMessage property will becalled and populated with the corresponding error message. The SDK programmermay also call the ErrorMessage property explicitly in code and populate it with acustomized error message.
Another feature of the FieldAddIn is the ParentHWnd parameter provided to theSelectFieldValue method. This provides a handle to the user’s current window andenables custom dialogs to be displayed to the user (even when the FieldAddIn isrunning on the server). It is not advisable to use dialogs in situations where noParentHWnd parameter is provided, as without a handle to the user’s window, thedialogs may be popping up on the server machine with nobody to answer them.
It is often desirable to access the object to which the user field undergoing theselection or verification belongs. This may be done using the FieldDefinition method‘GetCurrentObject’ for the user field passed to the FieldAddIn methods. In contrast,in the BaseObjectAddIn, the parent object to the user field is passed as a parameterto the SelectFieldValue and VerifyFieldValue methods, so when using theBaseObjectAddIn using the ‘GetCurrentObject’ method is not necessary.
HP TRIM 6 Software Development Kit
Page 31
BaseObjectAddIn
The BaseObjectAddIn is a generic AddIn that can respond to entry points within theSave or Delete process for any TRIM Object. Methods, within which custom code maybe placed, are shown below in blue.
Although the BaseObjectAddIn class is defined in the TRIMSDK Type Library (alongwith all the other TRIM SDK object classes), it is a special class, in that it is only aninterface definition, and the programmer must implement the interface to act uponmethod calls made by TRIM. (All other classes in the Type Library representinterfaces implemented by TRIM, and the programmer can call the methods on theseinterfaces).
The ErrorMessage property of the BaseObjectAddIn (not shown in the diagrambelow) provides some functionality for catching and displaying error messages to theuser. If any of the PreSave, PreDelete, or VerifyFieldValue methods return ‘false’, theErrorMessage property will be called and populated with the corresponding errormessage. The SDK programmer may also call the ErrorMessage property explicitly incode and populate it with a customized error message.
Another feature of the BaseObjectAddIn is the ParentHWnd parameter provided tothe SelectFieldValue method. This provides a handle to the user’s current windowand enables custom dialogs to be displayed to the user (even when the FieldAddIn isrunning on the server). It is not advisable to use dialogs in situations where noParentHWnd parameter is provided, as without a handle to the user’s window, thedialogs may be popping up on the server machine with nobody to answer them.
The SelectFieldValue and VerifyFieldValue methods of the BaseObjectAddIn differfrom the TRIMFieldAddIn in that a the object to which the user field belongs ispassed to the method. This enables the programmer to access other properties andfields of the parent object, which may be useful in selecting/verifying the value of theuser field. It may also be used to set other properties and fields of the parent objectat the time a value for the user field is selected or verified.
HP TRIM 6 Software Development Kit
Page 33
EventProcessor
The EventProcessor interface is an AddIn that responds to the processing of a TRIMEvent by the TRIM Event Processor. Methods, within which custom code may beplaced, are shown below in blue.
Although the TRIMEventProcessor class is defined in the TRIMSDK Type Library(along with all the other TRIM SDK object classes), it is a special class, in that it isonly an interface definition, and the programmer must implement the interface to actupon method calls made by TRIM. (All other classes in the Type Library representinterfaces implemented by TRIM, and the programmer can call the methods on theseinterfaces).
The range of events processed by the Event Processor is wide, but includes actionssuch as users logging on and off, records being created or modified, documentsbeing accessed, and various security-related events.
It is important to note that events are processed by the Event Processor (and theProcessEvent method called) at a later time to that at which the event occurred. As aresult the SDK programmer cannot rely on the object to which the event occurredstill being in the state indicated by the event, since the ProcessEvent method is notcalled in direct response to the event occurring. This must be taken into account inthe design of a program implementing the EventProcessor interface. For example, ifa hold is added to a record, the event ‘evHoldAdded’ is fired. However, by the timethe EventProcessor comes to process this ‘evHoldAdded’ event, the Hold may havealready been removed from the record, so you cannot rely on the record being undera Litigation Hold at the time the ‘evHoldAdded’ event is processed.
HP TRIM 6 Software Development Kit
Page 34
ActiveX Controls
In addition to the SDK's, which allow direct access to TRIM's data and functionality,the TRIM 5 and 6 SDK makes available certain components of the user interface asActiveX controls. These controls are core elements of TRIM's user interface that canbe built directly into another application's interface at design time.
The ActiveX controls have methods and properties that the programmer can accessto control the behavior and appearance of each instance of a control at run-time.They also fire events to notify their 'host' of user actions such as data entry andmouse clicks on the control, so that the application can take appropriate action.
There are three TRIM controls included in the SDK:
Document Viewer
Edit Box
Tree Box
The controls are contained in a component called "HP TRIM ActiveX Controls" andimplemented by the file "tsjOCX.dll"; the methods and properties are defined in theType Library "TRIMOCXLib".
HP TRIM 6 Software Development Kit
Page 35
Document Viewer - TRIMviewer
The Viewer control enables an application to view a wide variety of file formatswithout requiring the file's native application. The viewer control can be sized andpositioned according to the design requirements of the host application. Any file onthe file system can be viewed by the control (not just TRIM documents), so this canbe very useful as a preview control.(See Reference - ActiveX Controls - TRIMviewer.)
Edit Box - TRIMedit
An Edit Box is a standard control in Windows applications that is used to allow a userto type in or edit data. TRIM makes extensive use of edit boxes to capture userinput for record metadata and other information. In many cases, TRIM enhances thestandard edit box by providing a 'KwikSelect' button integrated into the control, toallow the user to interactively select an object from the TRIM Database, or a datefrom a calendar, or a file or directory from the local file system, instead of having totype the correct value manually. Many TRIM edit boxes also provide a history list,where the user's most recent selections of the same category (for example,Container files) are available in a drop-down list attached to the control.(See Reference - ActiveX Controls – TRIMedit.)
TRIM provides its own enhanced edit box control in the TRIM 5 and 6 SDK, soprogrammers and application designers can take advantage of the features itprovides in custom applications and dialogs. The control can be set to be one of thefollowing variations:
Custom Browser
Date Picker
Date and Time Picker
Input File Selector
Output File Selector
Directory Selector
Spelling Checker
Format Checker
The default behavior is pre-programmed into the control in all modes except CustomBrowser and Format checker modes. That is, if the control is set at design-time tobe a Date Picker, at run-time the control will display a calendar to the user when theKwikSelect is pressed, and the selected date will be entered into the text area of thecontrol. No code is required by the client programmer to provide this functionality.Similarly, if the control is set as an Input File selector, the standard File Open dialogis displayed for the user to select a file from their file system, and the name of theselected file is automatically entered in the text of the control.
If the control is set to be a Custom Browser or Format Checker then the programmerwill need to write code in response to the Browse event, which will be fired by thecontrol when the user presses the KwikSelect button. This is because the requiredbehavior will depend upon the context in which the control is being used.
HP TRIM 6 Software Development Kit
Page 37
Tree Box - TRIMtreeBox
The TRIM Tree Box control is used to display tabular data, i.e. rows of records withcolumns of record attributes. The rows may also be related in a hierarchy or treestructure, in which case the control will show the data rows in a Windows Explorer-style tree that can be navigated by the user expanding and collapsing branches.(See Reference - ActiveX Controls – TRIMtreeBox.)
The tree control uses enhanced column headers, which can be added, removed andreordered programmatically or interactively by the user. The headers can be resizedmanually or automatically to fit the data contents, and the user can sort the data byany column in ascending or descending order simply by clicking on a heading.
Like the other TRIM 5 and 6 ActiveX controls, the Tree control does not require aconnection to a TRIM Database, and it can be used to display non-TRIM data. Thecontrol is configured and populated by passing text strings to methods of the control.Many of TRIM's SDK objects have special methods that are designed specifically forthe Tree control, converting their data into appropriately formatted strings.
Common Scenarios – Code Samples
In this section, various common programming scenarios are discussed, with examplecode to illustrate how different tasks can be achieved.
HP TRIM 6 Software Development Kit
Page 38
Connecting to a Database
The Database object manages each client's connection to a Database, and in doingso it authenticates the current user (from their network login) and applies their TRIMsecurity profile when accessing any TRIM data. The Database object's Connectmethod will attempt to connect the user to their default Database. It does notrequire any parameters.
In Visual Basic:Dim objTRIM as TRIMSDK.DatabaseDim colDBs as New TRIMSDK.DatabasesIf colDBs.Count > 1 Then
' Let user select a Database in a dialogSet objTRIM = colDBs.ChooseOneUI(hWnd)
End IfobjTRIM.Connect
In C#:TRIMSDK.Database db = null;TRIMSDK.Databases colDBs = new TRIMSDK.Databases();if (colDBs.Count > 1){int hWnd = Handle.ToInt32();
// Let user select a Database in a dialogdb = colDBs.ChooseOneUI(hWnd);
}if ( db != null ){
db.Connect();}
Similarly, if a particular named Database is required, this could also be selectedprogrammatically from the Databases collection.
In Visual Basic:For i = 0 to colDBs.Count -1
Set objTRIM = colDBs.Item(i)If objTRIM.Name = "MyTRIM" Then
objTRIM.ConnectExit For
End IfNext
In C#:for ( int i=0; i < colDBs.Count; i++){
db = colDBs.Item(i);if (db.Name == "MyTRIM"){
db.Connect();break;
}}
HP TRIM 6 Software Development Kit
Page 39
Connecting to a default database
This sample code demonstrates connecting to a TRIM Database, when the HP TRIMInstallation is a default database, or there is only one database.
In Visual Basic:Dim objTRIM As TRIMSDK.DatabaseSet objTRIM = New TRIMSDK.DatabaseobjTRIM.Connect
In C#:TRIMSDK.Database db = new TRIMSDK.Database();db.Connect();
! Note: Calling the Connect method in this way is optional. If the Database
object is not connected when a method requiring a Database service is called,TRIM will automatically attempt a connection.
In Visual Basic:Dim objTRIM As TRIMSDK.DatabaseSet objTRIM = New TRIMSDK.Database' Connection is automatic when required if not explicitSet objRec = objTRIM.GetRecord(123)
In C#:TRIMSDK.Database db = new TRIMSDK.Database();// Connection is automatic when required if not explicitTRIMSDK.Record objRec = db.GetRecord(123);
If a different (non-default) Database is required, the Databases collection can beused to select a specific Database.
HP TRIM 6 Software Development Kit
Page 40
Connecting to a specific database
This sample code demonstrates connecting to a specific TRIM Database by settingthe database id.
In Visual Basic:Dim objTRIM As TRIMSDK.DatabaseSet objTRIM = New TRIMSDK.DatabaseobjTRIM.Id = “45” ‘45 is the id of the TRIM Demonstration DatabaseobjTRIM.Connect
In C#:TRIMSDK.Database db = new TRIMSDK.Database();db.Id = “45”; //45 is the id of the TRIM Demonstration Databasedb.Connect();
! Note: Calling the Connect method in this way is optional. If the Database
object is not connected when a method requiring a Database service is called,TRIM will automatically attempt a connection.
HP TRIM 6 Software Development Kit
Page 41
Allowing the user to choose a Database
Instantiates a Database selected by the user from a list of Databases.
Code Example – Visual Basic
Dim p_TRIMDatabaseCollection As TRIMSDK.DatabasesDim p_TRIMDatabase As TRIMSDK.Database
' Instantiate collection of valid TRIM DatabasesSet p_TRIMDatabaseCollection = New TRIMSDK.Databases
' Display the list of Databases.' Assign the selection to the modular level TRIM Database variableSet p_TRIMDatabase = p_TRIMDatabaseCollection.ChooseOneUI(hWnd)
If p_TRIMDatabase Is Nothing ThenDebug.Print "User Cancelled!"
ElseDebug.Print "TRIM Database " & p_TRIMDatabase.Name & " is Connected(T/F) - " &
p_TRIMDatabase.IsConnectedEnd If
' Release objectSet p_TRIMDatabaseCollection = Nothing
Code Example – C#// Instantiate collection of valid TRIM DatabasesTRIMSDK.Databases dbCol = new TRIMSDK.Databases();
// Display the list of Databases.// Assign the selection to the modular level TRIM Database variableint hWnd = Handle.ToInt32();TRIMSDK.Database db = dbCol.ChooseOneUI(hWnd);
if (db == null){
Console.WriteLine("User Cancelled!");}else{
Console.WriteLine( "TRIM Database " + db.Name + " is Connected(T/F) - " +db.IsConnected);}
// Release objectdbCol = null;
HP TRIM 6 Software Development Kit
Page 42
Showing and editing the properties of the TRIM Database object
This sample code demonstrates one method of customising the database propertiesin the SDK.
HP TRIM 6 Software Development Kit
Page 43
Code Example – Visual Basic
Private m_TRIMDatabase As TRIMSDK.Database
If m_TRIMDatabase.PropertiesUI(hWnd) ThenIf m_TRIMDatabase.Verify Then
m_TRIMDatabase.SaveElse
MsgBox "Error Saving Database properties " & m_TRIMDatabase.ErrorMessage,vbExclamation
End IfElse
Debug.Print "User Cancelled"End If
HP TRIM 6 Software Development Kit
Page 44
Code Example – C#
private TRIMSDK.Database db = new TRIMSDK.Database();
int hWnd = Handle.ToInt32();if (db.PropertiesUI(hWnd)){
if (db.Verify(false)){
db.Save();}else{
MessageBox.Show("Error Saving Database properties " + db.ErrorMessage,"",System.Windows.Forms.MessageBoxButtons.OK,System.Windows.Forms.MessageBoxIcon.Exclamation);
}}else{
Console.WriteLine( "User Cancelled");}
HP TRIM 6 Software Development Kit
Page 45
Accessing a Record
To read information stored on records in a TRIM Database, the API programmermust first determine how to access the records required. If a particular record'sinternal or external unique identifier is known, the associated record can be accesseddirectly and efficiently using the GetRecord method. (If neither of these uniqueidentifiers are known, it will be necessary to construct a search. This is covered inthe section Searching for Records.)
HP TRIM 6 Software Development Kit
Page 46
Getting a Record by Record Number
Every record in TRIM has a unique Record Number. This follows a pattern defined bythe Record Type and can be manually entered by the user or set to be automaticallygenerated by TRIM. Although the commonly used term is 'number', it is morecorrectly an identifier, as it is a string that may contain alphanumeric characters.This string is accessible through the Record object's Number property.
The Record Number can be used as the argument to be passed to the Databaseobject's GetRecord method, which takes a variant for the unique identifier andreturns a pointer to the instantiated Record.
For example, if you wish to instantiate the record 2002/0059, you need to use thefollowing statement:
In Visual Basic:Set objRecord = objTRIM.GetRecord ("2002/0059") ' instantiate by number
In C#:TRIMSDK.Record objRecord = db.GetRecord ("02/59"); //instantiate by number
! Note: TRIM stores the Record Number in two formats. The expanded format
(for example, "2002/0059") is held in the LongNumber property, and thecompressed format (for example, "02/59") is held in the Number property. Bothcan be passed to the GetRecord method.
HP TRIM 6 Software Development Kit
Page 47
Getting a Record by URI
The Unique Row Identifier or URI of a record is an internal unique number that istransparent to the everyday user of TRIM. It is the primary key on the TSRECORDtable in the Database and provides an internal unique identifier for every record.
To instantiate a record by its URI, you can pass the numeric URI as the argument tothe Database object's GetRecord method.See the following example:
In Visual Basic:Set objRecord = objTRIM.GetRecord (130) ' instantiate by URI
In C#:objRecord = db.GetRecord (130); // instantiate by URI
Once an instantiated record object has been returned by the GetRecord method, theprogrammer can access properties and call methods on the object. These arediscussed in the following subsections.
HP TRIM 6 Software Development Kit
Page 48
Reading Basic Properties
Most of the metadata directly associated with a record is exposed through propertieson the Record interface. Most properties return primitive data types (strings,numbers or dates) and can be interrogated directly. The meanings of theseproperties are generally self-evident from their names, but are also given in theobject browser and in the reference section.
Examples of basic readable properties of a record are:
Property Example valueNumber "G1997/0770"Title "Greenhouse Journal of Global Warming -
Dugong Habitats"DateCreated #8/20/1997#ExternalId "GJGW 97PB"AccessionNbr 5617
Visual Basic ExampleDim objRec As RecordSet objRec = objTRIM.GetRecord ("G97/770")If objRec.AccessionNbr > 5000 and objRec.DateCreated < #01/01/2000# Then
Msgbox objRec.Title, , "Record " & objRec.NumberEnd If
C# ExampleTRIMSDK.Database db = new TRIMSDK.Database();TRIMSDK.Record objRecord = db.GetRecord ("G97/770");DateTime date = new DateTime(2000,01,01);if (objRecord.AccessionNbr > 5000
&& objRecord.DateCreated < date){
MessageBox.Show (objRecord.Title, "Record " + objRecord.Number);}
HP TRIM 6 Software Development Kit
Page 49
Accessing Related Objects
Many attributes of a TRIM record represent other objects, such as the RecordType,Classification and Container attributes. These are properties where the data type ofthe property is an object interface reference.
Visual Basic Example
The following code instantiates a record object (in variable objRecord) and thenassigns its Container to another variable (objContainer).
Dim objRecord As RecordDim objContainer As RecordSet objRecord = objTRIM.GetRecord ("G99/15")Set objContainer = objRecord.Container ' objContainer is now 97/1004
C# Example
The following code instantiates a record object (in variable objRecord) and thenassigns its Container to another variable (objContainer).
TRIMSDK.Record objRecord = db.GetRecord ("G99/15");TRIMSDK.Record objContainer = objRecord.Container;// objContainer is now 97/1004
HP TRIM 6 Software Development Kit
Page 50
Accessing Record Location Information
A TRIM record has various properties concerning related location information. Theseproperties of a Record all return an instantiated Location object:
CurrentLoc – Current (Assignee) location of the record
HomeLoc – Normal location of the record
OwnerLoc – Location of the Owner or responsible Organization for the record
AuthorLoc – Person who authored the electronic document
CreatorLoc – Person who registered the record in TRIM
AddresseeLoc – Person to whom the record is addressed
PrimaryContactLoc – The main contact person (or organization) for the record.
To access the properties and methods of these location objects, you can create andinstantiate them using the following style of code:
In Visual Basic:Dim objRec as RecordDim objLoc as LocationSet objRec = objTRIM.GetRecord ("2002/0059") ' instantiate the recordSet objLoc = objRec.AuthorLoc ' get the author location objectMsgbox "Author's name is: " & objLoc.FormattedName
In C#:// instantiate the recordTRIMSDK.Record objRecord = db.GetRecord ("G99/15");// get the author location objectTRIMSDK.Location objLoc = objRecord.AuthorLoc;MessageBox.Show ("Author's name is:" + objLoc.FormattedName);
HP TRIM 6 Software Development Kit
Page 51
Updating Records
So far we have only considered the methods for reading information from records inTRIM. The SDK also allows you to update TRIM records, either by updating thevalues of properties on a given record object, or by calling methods on the record.
Updating properties is the simplest way to modify the metadata of a record. Yousimply assign a new value of the correct data type to the named property of theobject. Field-level verification is carried out, and an error will be raised if theproperty update is invalid (see also Verifying and Error Trapping section). For morecomplicated types of update to a record, you must generally call methods thatinstruct TRIM to modify the record, based on arguments passed.
HP TRIM 6 Software Development Kit
Page 52
Modifying Properties
The simplest way to update data in a TRIM record is to modify the named propertieson the Record object. This can only be done on properties that are not marked asread-only. This includes most of the Date properties, certain Location properties(AuthorLoc, AddresseLoc and OtherLoc) and miscellaneous properties such asExternal Id, Priority, Accession Number and Foreign Barcode.
Visual Basic ExampleSet objRecord = objTRIM.GetRecord(30)objRecord.Title = "New title for this record"objRecord.DateDue = Date + 10 ' Due in ten daysobjRecord.DatePublished = #20/05/2002#Set objRecord.AuthorLoc = objTRIM.CurrentUser
C# ExampleTRIMSDK.Record objRecord = db.GetRecord(30);objRecord.Title = "New Title for this record";objRecord.DateDue = DateTime.Today.AddDays(10);DateTime datePub = new DateTime(2002,05,20);objRecord.DatePublished = datePub;objRecord.AuthorLoc = db.CurrentUser;
HP TRIM 6 Software Development Kit
Page 53
Calling Update Methods
To update other data on a record where read-write properties are not available, youmust call a method instead. Update methods generally begin with the prefix 'Set…'and they include a parameter for the new data value you wish to apply.
In Visual Basic:Call objRecord.SetCurrentLocation(objMyUnitLoc);
In C#:TRIMSDK.Location objMyUnitLoc = db.CurrentUser;objRecord.SetCurrentLocation(objMyUnitLoc,DateTime.Today);
In many cases other parameters can be specified that control the behavior of theupdate:
In Visual Basic:' Set Current location to me, effective from yesterdayCall objRecord.SetCurrentLocation(objTRIM.CurrentUser, Date - 1)
In C#:// Set Current location to me, effective from yesterdayDateTime yesterday = DateTime.Today.AddDays(-1);objRecord.SetCurrentLocation(db.CurrentUser, yesterday);
HP TRIM 6 Software Development Kit
Page 54
Updating Properties Using SetProperty
To update a record's properties where the internal identifier of the property is known(see Property Ids), you can use the SetProperty method. This requires passing theproperty identifier and a variant containing the data value.
In Visual Basic:' Set the title (property id=3)Call objRecord.SetProperty(3, "Barrier Reef manatee population figures")
In C#:// Set the title (property id=3)objRecord.SetProperty(3, "Barrier Reef manatee population figures");
HP TRIM 6 Software Development Kit
Page 55
Verifying and Error Trapping
When a record object is modified via the SDK, there are two levels of verification thatmust be carried out before the changes can be committed to the Database.
The first is field-level verification, which checks that the change to an individualproperty is legal. An example would be to check that a Record’s Date Created is notin the future. If a property update cannot be carried out because of field-levelverification, the attempt to set the property will cause a run-time error to be raisedand the update will not be carried out.
The second level of validation is object-level verification (sometimes called cross-field verification.) This checks that the values of all fields on the object are consistentwith each other. An example of object-level verification would be that the DateRegistered is not earlier than the Date Created. Object-level verification may beperformed by the object’s Verify method. It is also carried out automaticallywhenever the object is saved.
Object-level verification for a single property may be performed by the base object’sVerifyProperty method. This checks that the value of a nominated property isconsistent with all other current values for the object. The VerifyProperty methodalso sn optional the capability to fail if the property is mandatory and has not beenset.
HP TRIM 6 Software Development Kit
Page 56
The Verify Method
The Record object (and every other base object) has a Verify method. This can becalled to perform object-level verification prior to saving the object. The methodreturns false if there are any errors in the state of the object, and the errordescription will be stored in the object's ErrorMessage property. If there are noerrors, the method returns true and the Verified property (see The Verified Property)is set to true.
The method contains an optional parameter FailOnWarnings which, if set to true, willcause the Verify method to check for warning conditions as well as error conditions,and to fail if a warning is encountered.
Visual Basic ExampleIf Not objRecord.Verify(True) Then
Msgbox objRecord.ErrorMessage,,"Verify Failed"Else
objRecord.SaveEnd If
C# Exampleif (! objRecord.Verify(true)){
MessageBox.Show(objRecord.ErrorMessage,"Verify Failed");}else{
objRecord.Save();}
If it is not called explicitly in code, the Verify method will be automatically calledbefore an object is saved and if verification fails it will not be saved. This ensuresthat data cannot become corrupted and that business rules are observed when usingthe SDK, just as they are for users of the TRIM Client interface.
HP TRIM 6 Software Development Kit
Page 57
The VerifyProperty Method
The VerifyProperty method may be used to cross-check the value of a single propertyagainst all other property and field values for the object. It is only available from theIBaseObject interface for the object. If the VerifyProperty method fails to verify theproperty, the object’s ErrorMessage property will be populated with the details of thefailure.
The following code example demonstrates a case in which the VerifyProperty methodwill fail as a result of assigning an invalid value for the DatePublished property.
Visual Basic Example
'Assuming objTRIM is a connected database object
Dim objRecord As RecordDim recType As RecordTypeDim baseObj As IBaseObject
Set recType = objTRIM.GetRecordType("Document")Set objRecord = objTRIM.NewRecord(recType)objRecord.Title = "Test Record"objRecord.Save
objRecord.DatePublished = objRecord.DateCreated - 1Set baseObj = objRecord
'Now we verify the DatePublished property (property id = 111)'This will fail since the date published must be later than the date created'and we have not set a value for itIf Not baseObj.VerifyProperty(111, False) ThenMsgBox objRecord.ErrorMessage, , "VerifyProperty failed"End If
C# Example
//Assumming db is a connected database object
RecordType recType = db.GetRecordType("Document");RecordClass rec = (RecordClass)db.NewRecord(recType);rec.Title = "Test Record";rec.Save();rec.DatePublished = rec.DateCreated.AddDays(-1);IBaseObject recBaseObj = (IBaseObject)rec; //retrieves the base object for this record
//Now we verify the DatePublished property (property id = 111)//This will fail since the date published must be later than the date createdif (! rec.VerifyProperty(111, false)){
MessageBox.Show(rec.ErrorMessage,"VerifyProperty failed");}
The second parameter of the VerifyProperty method gives the programmer theadditional option to check whether the property is mandatory. If using this option,the VerifyProperty method will fail if the property is mandatory and has not yet beengiven a value.
The following code example demonstrates a case in which the VerifyProperty method
HP TRIM 6 Software Development Kit
Page 58
will fail as a result of not setting a mandatory property.
Visual Basic Example
'Assuming objTRIM is a connected database object
Dim objRecord As RecordDim recType As RecordTypeDim baseObj As IBaseObject
Set recType = objTRIM.GetRecordType("Document")Set objRecord = objTRIM.NewRecord(recType)Set baseObj = objRecord
'Now we verify the title property (property id = 3)'This will fail since the title property is mandatory'and we have not set a value for itIf Not baseObj.VerifyProperty(3, True) Then
MsgBox objRecord.ErrorMessage, , "VerifyProperty failed"End If
C# Example
//Assumming db is a connected database object
RecordType recType = db.GetRecordType("Document")Record rec = db.NewRecord(recType);IBaseObject recBaseObj = rec; //retrieves the base object for this record
//Now we verify the title property (property id = 3)//This will fail since the title property is mandatory//and we have not set a value for itif (! recBaseObj.VerifyProperty(3, True)){
MessageBox.Show(objRecord.ErrorMessage,"VerifyProperty failed");}
HP TRIM 6 Software Development Kit
Page 59
The Verified Property
Base objects also have a Verified Boolean read-only property, which is falsewhenever the object is instantiated. It is set to true when the Verify methodconfirms that it is in a legal state to be saved to the Database.
Visual Basic Example
The following code demonstrates how the Verified property changes according to thestate of the object.
' To demonstrate the Verified property
Dim objTRIM As TRIMSDK.DatabaseSet objTRIM = New TRIMSDK.Database
' Instantiate the RecordDim objRecord As TRIMSDK.RecordDim msg As StringDim oldTitle As StringSet objRecord = objTRIM.GetRecord("02/59")msg = "The Record object has just been instantiated. Verified property is set to: " &objRecord.VerifiedMsgBox (msg)' Verify the Record, with default FailOnWarnings = falseobjRecord.Verify (False)msg = "The Record has just been verified. Verified property is set to: " &objRecord.VerifiedMsgBox (msg)oldTitle = objRecord.Titlemsg = "Would you like to change the title of the Record?"If MsgBox(msg, vbYesNo, vbQuestion) = VbMsgBoxResult.vbYes Then
objRecord.Title = "new Title"msg = "The title of the Record has just been changed. The Record has not yet been
checked for internal consistency. Verified property is set to: " & objRecord.VerifiedMsgBox (msg)
Elsemsg = "No changes have been made, so the Record is still internally consistent.
Verified property is set to: " & objRecord.VerifiedMsgBox(msg)
End If' now save the changes if the object is verifiedIf Not objRecord.Verified Then
If objRecord.Verify() ThenobjRecord.Savemsg = "The changes made to the Record have been verified, and it has just
been saved (so the changes are now committed to the Database). The Verified property isnow set to: " & objRecord.Verified
MsgBox (msg)Else
msg = "Record Verify failed:" & objRecord.ErrorMessage & ". Because ofthis, it has not been saved."
MsgBox (msg)End If
Elsemsg = "Record was verified, so there were no changes to save.")MsgBox(msg)
End IfMsgBox ("Reverting back to original title of record...")objRecord.Title = oldTitleobjRecord.Save
C# Example
The following code demonstrates how the Verified property changes according to thestate of the object.
// To demonstrate the Verified property
HP TRIM 6 Software Development Kit
Page 60
// Instantiate the RecordTRIMSDK.Record objRecord = db.GetRecord("02/59");MessageBox.Show("The Record object has just been instantiated. Verified property is setto: " + objRecord.Verified);// Verify the Record, with default FailOnWarnings = falseobjRecord.Verify(false);MessageBox.Show("The Record has just been verified. Verified property is set to: " +objRecord.Verified);string oldTitle = objRecord.Title;if (MessageBox.Show("Would you like to change the title of the Record?","",MessageBoxButtons.YesNo, MessageBoxIcon.Question) == DialogResult.Yes){
objRecord.Title = "new Title";MessageBox.Show("The title of the Record has just been changed. The Record has
not been checked for internal consistency. Verified property is set to: " +objRecord.Verified);}else{
MessageBox.Show("No changes have been made, so the Record is still internallyconsistent. Verified property is set to: " + objRecord.Verified);}// now save the changes if the object is verifiedif (! objRecord.Verified){
if (objRecord.Verify(false)){
objRecord.Save();MessageBox.Show("The changes made to the Record have been verified, and it
has just been saved (so the changes are now committed to the Database). The Verifiedproperty is now set to: " + objRecord.Verified);
}else{
MessageBox.Show("Record Verify failed:" + objRecord.ErrorMessage + ".Because of this, it has not been saved. The Verified property is now set to: " +objRecord.Verified);
}}else{
MessageBox.Show("Record was verified, so there were no changes to save. TheVerified property is now set to: " + objRecord.Verified);}MessageBox.Show("Reverting back to original title of record...");objRecord.Title = oldTitle;objRecord.Save();
HP TRIM 6 Software Development Kit
Page 61
Trapping Run-Time Errors
It is up to the programmer to determine how they wish to deal with possible errorswhen updating an object. However, they must be aware that error checking takesplace even when directly updating properties, so it will be necessary to provide someerror-trapping code to prevent run-time errors being displayed to the user if there isa possibility of errors being raised.
HP TRIM 6 Software Development Kit
Page 62
Saving the Record to the Database
All of the update methods and property changes made through the Record interfaceare only applied to the object in memory. The changes are not committed to theTRIM Database until the object is saved.
Calling the Save method on the record object will commit the changes to theDatabase, applying all updates since the object was instantiated (or since it was lastsaved).
! Note: that if the record has not been verified, Save will automatically call theVerify method and will only commit the changes if the verification succeeds.
Visual Basic ExampleSet objRecord = objTRIM.GetRecord("G97/770")With objRecord
.Title = .Title & " plus New Part of Title"
.DateDue = #1/1/2003#Set .AuthorLoc = objTRIM.CurrentUserCall .Save ' commit all these changes to the Database
End With
C# ExampleTRIMSDK.Record objRecord = db.GetRecord("G97/770");objRecord.Title = objRecord.Title + " plus New Part of Title";DateTime dateDue = new DateTime(2003,1,1);objRecord.DateDue = dateDue;objRecord.AuthorLoc = db.CurrentUser;objRecord.Save(); // commit all these changes to the Database
HP TRIM 6 Software Development Kit
Page 63
Searching for Records
One of the most powerful features of TRIM is the wide range of search criteria thatcan be applied to select records from the Database. The SDK has many featuresavailable for creating complex and sophisticated searches, yet it can also be usedwith a minimum of code.
The RecordSearch object enables TRIM records to be retrieved by creating a searchexpression from a number of search clauses, and has methods to navigate therecords that meet the search criteria. The RecordSearch object also allows booleanand, or and not relationships to logically combine search clauses, and setting filtersand sort criteria. The object also has file functions for saving searches to or loadingfrom disk.
To set the search criteria for a record search, you can either call search clausemethods explicitly, or display the TRIM search dialog to allow the user to specify thesearch criteria, or a combination of the two.
The process of searching for records via the SDK is as follows:
1. Construct a RecordSearch object
2. Add a search clause
3. Add additional clauses and combine them with logical operators (optional)
4. Apply Record Type filters (optional)
5. Display the criteria to the user (optional)
6. Execute the search query
7. Process the results sequentially, or
8. Copy the results to a record collection.
Visual Basic ExampleDim objSearch As RecordSearchDim colRecords As Records' Construct a new search objectSet objSearch = objTRIM.NewRecordSearch' Search for "reef" in record titlesCall objSearch.AddTitlewordClause("reef")' Hold the results in a collectionSet colRecords = objSearch.GetRecords
C# Example// Construct a new search objectTRIMSDK.RecordSearch objSearch = db.NewRecordSearch();// Search for "reef" in record titlesobjSearch.AddTitleWordClause("reef");// Hold the results in a collectionTRIMSDK.Records colRecords = objSearch.GetRecords();
HP TRIM 6 Software Development Kit
Page 64
Creating a RecordSearch Object
Like any other object, the RecordSearch object must be constructed by the Databaseobject, in this case using the NewRecordSearch method. A RecordSearch object is atemporary object, and therefore does not need to be instantiated from the Database(the exception to this is Saved Searches, which will be covered later.)
Visual Basic ExampleDim objSearch As RecordSearch ' declare the search objectSet objSearch = objTRIM.NewRecordSearch ' make the objectCall objSearch.EditQueryUI(hWnd) ' call methods on the object…
C# Example// declare & make the search objectTRIMSDK.RecordSearch objSearch = db.NewRecordSearch();int hWnd = Handle.ToInt32();objSearch.EditQueryUI(hWnd); // call methods on the object…
HP TRIM 6 Software Development Kit
Page 65
Adding a Search Clause
Once you have created the search object, you must then add at least one searchclause before it can be executed to return results. There are many different searchclauses available; the full list can be found in the Reference section.
For example, to retrieve records that contain the word "reef" within the title, youwould add a Title Word clause passing the argument "reef", as follows:
In Visual Basic:objSearch.AddTitlewordClause("reef") ' search for titles with "reef"
In C#:objSearch.AddTitleWordClause("reef"); //search for titles with "reef"
To retrieve records that were created since January 1, 2001, you would add a DateCreated clause passing the arguments "1/1/2001" and the current date, as follows:
In Visual Basic:objSearch.AddDateCreatedClause(#01/01/2001#, Date)
In C#:System.DateTime dateCreated = new DateTime(2001,01,01);objSearch.AddDateCreatedClause(dateCreated, DateTime.Today);
You can build search criteria by calling multiple methods, and applying specific logicalrelationships, using the Boolean operators, as described below.
HP TRIM 6 Software Development Kit
Page 66
Boolean Operators - And, Or, Not
An advanced search can be constructed by combining several search clauses with theBoolean operators 'And', 'Or' and 'Not'. When a Boolean operator is applied to twoclauses (or one in the case of 'Not') the result is a single clause. This resultantclause can also be the subject of another Boolean operation.
The sequence in which these clauses and operators must be declared in the searchobject is known as Reverse Polish Notation. Clauses (or 'operands') are declaredfirst, and then an Operator is declared. This operates on the last two declaredclauses (or the last one for a 'Not' operation). The clauses affected by the operationare replaced by a single clause representing the Boolean combination.
For example, consider the following sequence of declarations:Clause: AClause: BOperator: NotOperator: And
This results in the logical proposition: 'A and (not B)'.
Another example, this time using RecordSearch object methods:
In Visual Basic:objSearch.AddTrayClause(ttWorkTray)objSearch.AddDateCreatedClause(Date, Date)objSearch.AddCaveatClause("Medical in Confidence")objSearch.NotobjSearch.AndobjSearch.OrobjSearch.AddLocationClause(objAdminLoc, ltCurrent)objSearch.And
In C#:objSearch.AddTrayClause(ttTrayType.ttWorktray);DateTime dateFrom = new DateTime(2001,1,1);DateTime dateTo = new DateTime(2002,1,1);objSearch.AddDateCreatedClause(dateFrom, dateTo);objSearch.AddCaveatClause("Medical in Confidence");objSearch.Not();objSearch.And();objSearch.Or();TRIMSDK.Location objAdminLoc = db.GetLocation("Administration");objSearch.AddLocationClause(objAdminLoc, ltSearchLocationType.ltCurrent, true);objSearch.And();
This results in the search: "(Records in my Worktray or (created today and withoutthe Caveat Ministerial in Confidence)) and currently located in Administration unit".
HP TRIM 6 Software Development Kit
Page 67
User Selected Search Criteria
In many cases the programmer will not know the details of the search criteria andinstead will delegate the search criteria to the user. To do this, you can call theRecordSearch object's EditQueryUI method. This will display the TRIM Search dialogto the user and update the object's search criteria according to their selections.
You can pre-populate the search criteria by calling a search method before callingthe EditQueryUI method. If you specify multiple search methods prior to calling it,the Advanced Search dialog will be displayed.
Visual Basic ExampleSet objSearch = objTRIM.NewRecordSearchCall objSearch.AddTitleWordClause("Press")Call objSearch.AddDateRegisteredClause((Date – 1), Date)Call objSearch.AndIf Not objSearch.EditQueryUI(hWnd) Then
Exit Sub ' (Search dialog cancelled)End If
C# ExampleTRIMSDK.RecordSearch objSearch = db.NewRecordSearch();objSearch.AddTitleWordClause("Press");DateTime yesterday = DateTime.Today.AddDays(-1);DateTime today = DateTime.Today;objSearch.AddDateRegisteredClause(yesterday, today);objSearch.And();int hWnd = Handle.ToInt32();if (! objSearch.EditQueryUI(hWnd)){
return; // (Search dialog cancelled)}
HP TRIM 6 Software Development Kit
Page 68
Applying Filters
An optional step in searching for records is to filter the returned records on the basisof Record Type, disposition, class and finalized status. The default is to include allrecords that meet the criteria, regardless of these categories. To apply filtering,there are methods on the RecordSearch object prefixed with 'Filter…'
Visual Basic ExampleWith objSearch
.AddTitleWordClause("manatee")
.FilterClass(rcReference) ' include only Reference class
.FilterDisposition(rdDestroyed, False) ' include all except Destroyed
.FilterTypes(colMyTypes) ' include Types matching this collectionEnd With
C# ExampleobjSearch.AddTitleWordClause("manatee");// include only Reference classobjSearch.FilterClass(rcRecordClass.rcReference,true);// include all except DestroyedobjSearch.FilterDisposition(rdRecordDisp.rdDestroyed, false);// include Types matching this collectionobjSearch.FilterRecordTypes(colMyTypes);
HP TRIM 6 Software Development Kit
Page 69
Sorting
Another optional step when constructing a record search is to define the sort orderfor the search results.
The Sort method allows you to specify up to three different sort criteria, and whetherto sort in ascending (the default) or descending order for each.
The following example sorts the results by ascending Priority, then Record Type,then descending Date Due.
In Visual Basic:Call objSearch.Sort(rsPiority,,rsRecordType,,rsDateDue, True)
In C#:objSearch.Sort(rsRecordSortFields.rsPriority,false,rsRecordSortFields.rsRecordType,false,rsRecordSortFields.rsDateDue, true);
HP TRIM 6 Software Development Kit
Page 70
Displaying Results
Once the search criteria, filters and sort order have been specified, you can retrievethe records that match the criteria. These records can either be processedsequentially in code (see Processing Results Sequentially) or they can be copied to arecord collection for reporting or displaying to the user.
To copy the results to a Records collection, you must call the GetRecords method.
Visual Basic ExampleDim objSearch As RecordSearchDim colResults As RecordsSet objSearch = objTRIM.NewRecordSearchCall objSearch.AddTitleWordClause("water")Set colResults = objSearch.GetRecordsCall colResults.DisplayUI(hWnd) ' browse the results
C# ExampleTRIMSDK.RecordSearch objSearch = db.NewRecordSearch();objSearch.AddTitleWordClause("water");TRIMSDK.Records colResults = objSearch.GetRecords();int hWnd = Handle.ToInt32();colResults.DisplayUI(hWnd); // browse the results
When the results have been copied to a Records collection, you have several optionsfor displaying records, including allowing the user to select one record(ChooseOneUI), to select multiple records (ChooseManyUI) or simply to browse theresults for viewing (DisplayUI).
HP TRIM 6 Software Development Kit
Page 71
Processing Results Sequentially
If there is no need to display the search results or to handle them as a collection ofrecords, they can be retrieved one at a time by repeatedly calling the Next method.This returns a single Record object each time it is called (returning a null objectwhen there are no more records to return.)
Code Example – Visual Basic
In this example, all records returned by the search are processed by adding up thevalues in a User Defined Field called 'Actual Cost', subtotalled by month based on thedate the record was created.
Dim sCosts(12) As SingleDim iMonth As Integer' Get the user-defined field "Actual Cost"Dim objCost As FieldDefinitionSet objCost = objTRIM.GetFieldDefinition("Actual Cost")' Create the searchSet objSearch = objTRIM.NewRecordSearchCall objSearch.AddTitleWordClause("Project Cost Report")' Process the results in a loopSet objRecord = objSearch.NextDo Until objRecord Is Nothing
iMonth = Month(objRecord.DateCreated)sCosts(iMonth) = sCosts(iMonth) + objRecord.GetUserField(objCost)Set objRecord = objSearch.GetNext
Loop
Code Example – C#
In this example, all records returned by the search are processed by adding up thevalues in a User Defined Field called 'Actual Cost', subtotalled by month based on thedate the record was created.
double[] sCosts = new double[12];int iMonth;// Get the user-defined field “Actual Cost”TRIMSDK.FieldDefinition objCost = db.GetFieldDefinition("Actual Cost");// Create the searchTRIMSDK.RecordSearch objSearch = db.NewRecordSearch();objSearch.AddTitleWordClause("Project Cost Report");// Process the results in a loopTRIMSDK.Record objRecord = objSearch.Next();while (objRecord != null){
iMonth = objRecord.DateCreated.Month;double cost =
Convert.ToDouble(objRecord.GetUserField(objCost,TRIMSDK.sdStringDisplayType.sdDefault))sCosts[iMonth] = sCosts[iMonth] + cost;objRecord = objSearch.GetNext();
}
HP TRIM 6 Software Development Kit
Page 72
Code Examples – Visual Basic
Simple Record Search
Adds a TitleWord clause to the Record Search object to find a specifiedindexed Word.
The user to selects a record and instantiates a Record.
Methods
o AddTitleWordClause
o GetRecords
o ChooseOneUI
Properties
o ErrorMessage
Visual Basic Code:// Assumes TRIMDatabase is a valid TRIMSDK Database// Instantiate a new TRIM record search objectSet RecordSearch = TRIMDatabase.NewRecordSearch
If Not RecordSearch.AddTitleWordClause(txtLookFor.Text) ThenMsgBox "Add Title Word Clause error " & RecordSearch.ErrorMessage, vbExclamationExit Sub
End If// Fill the Records Collection from the Search objectSet RecordResults = RecordSearch.GetRecords// Instantiate a record by choosing it from the collectionSet RecordItem = RecordResults.ChooseOneUI(hWnd)If RecordItem Is Nothing Then
Debug.Print "User cancelled!"Else
Debug.Print RecordItem.Number & " - " & RecordItem.TitleEnd If
HP TRIM 6 Software Development Kit
Page 73
Boolean ‘Or’ Record Search
Record search - Adds two TitleWord clauses with an Or to the Record Searchobject in order to find records with title words of txtSearch1.Text ortxtSearch2.Text.
The user to selects a record and instantiates a Record.
Methods
o AddTitleWordClause
o Or
o GetRecords
o ChooseOneUI
Properties
o ErrorMessage
Visual Basic Code:' Assumes TRIMDatabase is a valid TRIMSDK Database' Instantiate a new TRIM record search objectSet p_RecordSearch = TRIMDatabase.NewRecordSearchIf Not p_RecordSearch.AddTitleWordClause(txtSearch1.Text) Then
MsgBox "Add Title Word Clause error " & p_RecordSearch.ErrorMessage, vbExclamationExit Sub
End IfIf Not p_RecordSearch.AddTitleWordClause(txtSearch2.Text) Then
MsgBox "Add Title Word Clause error " & p_RecordSearch.ErrorMessage, vbExclamationExit Sub
End IfIf Not p_RecordSearch.Or Then
MsgBox "Adding Boolean 'OR' failed " & p_RecordSearch.ErrorMessage, vbExclamationExit Sub
End If' Fill the Records Collection from the Search objectSet p_RecordResults = p_RecordSearch.GetRecords' Instantiate a record by choosing it from the collectionSet p_RecordItem = p_RecordResults.ChooseOneUI(hWnd)If p_RecordItem Is Nothing Then
Debug.Print "User cancelled!"Else
Debug.Print p_RecordItem.Number & " - " & p_RecordItem.TitleEnd If
HP TRIM 6 Software Development Kit
Page 74
Saved Search
Create a Saved Search. Save the record search object.
Methods
o PropertiesUI
o Verify
o Save
Properties
o Name
o ErrorMessage
Visual Basic Code:' Display the properties of a RecordSearch object' returns True if the user presses OKIf p_RecordSearch.PropertiesUI(hWnd) Then
If p_RecordSearch.Verify(True) Then' If no errors or warnings, Save the Record Searchp_RecordSearch.SaveMsgBox "Saved Search created - " & p_RecordSearch.Name, vbInformation
Else' Display ErrorsMsgBox "Record Search Verify failed: " & p_RecordSearch.ErrorMessage,
vbExclamationEnd If
End If
HP TRIM 6 Software Development Kit
Page 75
Code Examples – C#
Simple Record Search
Adds a TitleWord clause to the Record Search object to find a specifiedindexed Word.
The user to selects a record and instantiates a Record.
Methods
o AddTitleWordClause
o GetRecords
o ChooseOneUI
Properties
o ErrorMessage
C# Code:// Assumes TRIMDatabase is a valid TRIMSDK Database// Instantiate a new TRIM record search objectTRIMSDK.RecordSearch recordSearch = db.NewRecordSearch();if (! recordSearch.AddTitleWordClause("title")){
MessageBox.Show( "Add Title Word Clause error " + recordSearch.ErrorMessage, "",MessageBoxButtons.OK,MessageBoxIcon.Exclamation);
return;}// Fill the Records Collection from the Search objectTRIMSDK.Records recordResults = recordSearch.GetRecords();// Instantiate a record by choosing it from the collectionint hWnd = Handle.ToInt32();TRIMSDK.Record recordItem = recordResults.ChooseOneUI(hWnd);if (recordItem == null){
Console.WriteLine( "User cancelled!");}else{
Console.WriteLine( recordItem.Number + " - " + recordItem.Title);}
HP TRIM 6 Software Development Kit
Page 76
Boolean ‘Or’ Record Search
Record search - Adds two TitleWord clauses with an Or to the Record Searchobject in order to find records with title words of txtSearch1.Text ortxtSearch2.Text.
The user to selects a record and instantiates a Record.
Methods
o AddTitleWordClause
o Or
o GetRecords
o ChooseOneUI
Properties
o ErrorMessage
C# Code:// Assumes TRIMDatabase is a valid TRIMSDK Database// Instantiate a new TRIM record search objectTRIMSDK.RecordSearch recordSearch = db.NewRecordSearch();if (! recordSearch.AddTitleWordClause("txtSearch1.Text")){
MessageBox.Show("Add Title Word Clause error " + recordSearch.ErrorMessage, "",MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
return;}if (! recordSearch.AddTitleWordClause("txtSearch2.Text")){
MessageBox.Show( "Add Title Word Clause error " + recordSearch.ErrorMessage, "",MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
return;}if (! recordSearch.Or()){
MessageBox.Show( "Adding Boolean 'OR' failed " + recordSearch.ErrorMessage, "",MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
return;}// Fill the Records Collection from the Search objectTRIMSDK.Records recordResults = recordSearch.GetRecords();// Instantiate a record by choosing it from the collectionTRIMSDK.Record recordItem = recordResults.ChooseOneUI(Handle.ToInt32());if (recordItem == null){
Console.WriteLine( "User cancelled!");}else{
Console.WriteLine( recordItem.Number + " - " + recordItem.Title);}
HP TRIM 6 Software Development Kit
Page 77
Saved Search
Create a Saved Search. Save the record search object.
Methods
o PropertiesUI
o Verify
o Save
Properties
o Name
o ErrorMessage
C# Code:TRIMSDK.RecordSearch recordSearch = db.NewRecordSearch();int hWnd = Handle.ToInt32();// Display the properties of a RecordSearch object// returns True if the user presses OKif (recordSearch.PropertiesUI(hWnd)){
if (recordSearch.Verify(true)){
// If no errors or warnings, Save the Record SearchrecordSearch.Save();MessageBox.Show( "Saved Search created - " + recordSearch.Name, "",
MessageBoxButtons.OK, MessageBoxIcon.Information);}else{
// Display ErrorsMessageBox.Show( "Record Search Verify failed: " +
recordSearch.ErrorMessage, "", MessageBoxButtons.OK, MessageBoxIcon.Exclamation);}
}
HP TRIM 6 Software Development Kit
Page 78
Creating a Container File
This scenario describes the general processes for using the SDK to create a record ofa generic Record Type we are calling a 'Container File'. In this and the next scenario(Creating a Document) we are assuming that the reader is familiar with the conceptof Record Types. These are described in HP TRIM Help – Administrator Guide –Record Types.
While it is up to the Administrator of each TRIM implementation to determine theRecord Types to be used, it is typical to follow a standard records managementpractise of having at least two Record Types, one representing Container Files (orFolders) and one representing Documents (the actual names used for the RecordTypes may of course vary.) Container Files are usually created and maintained byspecialist records managers, as it is generally at this level that Classificationsystems, Retention Schedules, Security, Thesaurus Terms (keywords), controlledtitling and other records management metadata are applied. Documents, on theother hand, are usually created by end-users, and require little specific metadataother than the identification of the appropriate Container File to which the Documentbelongs, as all other metadata and context is inherited from the Container.
The general steps for creating a new Container File record are as follows:
1. Instantiate the appropriate Record Type object
2. Instantiate a new Record object of this Type
3. Identify the Classification or Keywords for titling the record (optional)
4. Set the free text title
5. Assign Security Levels and Caveats (optional)
6. Relate the record to associated Locations (optional)
7. Relate to other records (optional)
8. Assign other metadata or User Defined Fields (optional)
9. Assign a record identifier
10. Save the Record object.
HP TRIM 6 Software Development Kit
Page 79
Creating a Record of a given Type
When creating any record, the Record Type for the new record must be identified.This can be done programmatically if the Record Type's URI or Name is known atdesign-time, or the choice may be given to the user at run-time. In either case, theend result is to instantiate an existing Record Type object (using the GetRecordTypemethod), and to pass this object to the Database object's NewRecord method.
In Visual Basic:' Create a new Case File recordSet objRecType = objTRIM.GetRecordType("Case File")Set objRecord = objTRIM.NewRecord(objRecType)
In C#://Create a new Case File recordTRIMSDK.RecordType objRecType = db.GetRecordType("Case File");TRIMSDK.Record objRecord = db.NewRecord(objRecType);
! Note: It is possible to create new Record Types using the SDK; however, this
is not recommended as this is generally an Administrator's function only.)
HP TRIM 6 Software Development Kit
Page 80
Controlled and Free Text Titling
Titles for Container Files are often subject to controlled vocabulary or Classificationstructures such as a Thesaurus or Classification (file) plan, which give recordsmanagers greater control over file creation, retrieval and Retention. Even when suchcontrolled titling is used, each file will typically also have a 'free text' title part. Thetitling method used is determined by the Record Type, and is usually set by the TRIMAdministrator. Thus a record with Classification titling may have a title such as:"Insurance – Property – Storm damage to Mackay information center", where thefirst two terms are generated from a predefined hierarchical Classification structureand the remaining part of the title is 'free text' describing the specifics of the file.The generated title terms are determined by the Classification codes, usually definedas a numerical sequence such as "610/600/". The free text title is set via theTypedTitle property.
Visual Basic ExampleIf objRecordType.TitlingMethod = tmClassification Then
' Assign classification of 610/600/ = Insurance – PropertyobjRecord.Classification = objTRIM.GetClassification("610/600/")
End IfobjRecord.TypedTitle = "Storm damage to Mackay information center"
C# Exampleif (objRecordType.TitlingMethod == tmTitlingMethods.tmClassification){
// Assign classification of 610/600/ = Insurance - PropertyobjRecord.Classification = db.GetClassification("610/600/");
}objRecord.TypedTitle = "Storm damage to Mackay information center";
Similarly, Thesaurus (or Keyword) titling allows a file to be titled using either achoice of individual keywords from a controlled list or a specific 'branch' of relatedterms according to a hierarchical structure (similar to a record plan or Classification.)A Thesaurus-titled file might have a name such as "Administration – Finance –Donations – Bequest from the estate of Lady Marchcroft".
Visual Basic ExampleobjRecord.GeneratedTitle = "Administration - Finance - Donations"objRecord.TypedTitle = "Bequest from the estate of Lady Marchcroft"
C# ExampleobjRecord.GeneratedTitle = "Administration - Finance - Donations";objRecord.TypedTitle = "Bequest from the estate of Lady Marchcroft";
HP TRIM 6 Software Development Kit
Page 81
Security Levels and Caveats
The security profile of an individual TRIM record is governed by three securitycontrols: a Security Level, a set of zero or more Caveats, and Access Control.(See TRIM.chm – Administrator Guide – Ch1 - Security.)Access Control is discussed in the next section.
Security Levels and Caveats determine the access that a TRIM user has to themetadata of a record. These security specifications are usually applied to RecordTypes (and inherited by records of each type when they are created) but can be setexplicitly on individual records. Every user has a maximum Security Level and zeroor more Caveats – in order to access a particular record, the user must have thesame or a higher Security Level and must have all the Caveats associated with therecord.
Assigning Security Levels and Caveats to a record via the SDK is straightforward.Both the SecurityLevel object and the SecurityCaveat object can be instantiated byfull name or by abbreviation. The instantiated SecurityLevel object is assigned to therecord's SecLevel property. Each instantiated SecurityCaveat object can be passedto the record's AddCaveat method.
Visual Basic ExampleDim objCav as SecurityCaveatDim objSec as SecurityLevel' Assign "Confidential" levelSet objSec = objTRIM.GetSecurityLevel("Confidential")Set objRecord.SecLevel = objSec' Assign "Research Projects" CaveatSet objCav = objTRIM.GetSecurityCaveat("Research Projects")Call objRecord.AddCaveat(objCav)' Assign "Staff in Confidence" CaveatCall objRecord.AddCaveat(objTRIM.GetSecurityCaveat("Staff in Confidence"))
C# Example// Assign "Confidential" levelTRIMSDK.SecurityLevel objSec = db.GetSecurityLevel("Confidential");objRecord.SecLevel = objSec;// Assign "Research Projects" CaveatTRIMSDK.SecurityCaveat objCav = db.GetSecurityCaveat("Research Projects");objRecord.AddCaveat(objCav);// Assign "Staff in Confidence" CaveatobjRecord.AddCaveat(db.GetSecurityCaveat("Staff in Confidence"));
! Note: that it is also possible to assign a string value of comma-separatedSecurity Level and Caveat names (not abbreviations) to the Record object'sSecurity property. If the string can be completely parsed into legal securityvalues, they will be assigned to the record. The following code produces thesame result as the example above:
Visual Basic Example' Assign security level and two CaveatsobjRecord.Security = "Confidential, Research Projects, Staff in Confidence"
C# Example// Assign security level and two CaveatsobjRecord.Security = "Confidential, Research Projects, Staff in Confidence";
HP TRIM 6 Software Development Kit
Page 82
Access Control
In addition to Security Levels and Caveats, Access Control provides fine-grainedcontrol over different methods of access to a record and its electronic attachment.(See TRIM.chm – Administrator Guide – Ch 1- Security – Access Control.)
Access Control associates individual users or groups of users with specific actionsallowed for a record. The actions are:
reading metadata
updating metadata
viewing the electronic object
updating the electronic object
deleting the record
changing Access Control details
Each action can be granted access as follows:
Public (all users)
Private (only one user)
Inherited (same access as the Container record)
Ad hoc (a set of named locations)
The default for a record that has no Access Control specified is that all users canperform all actions (subject to Security Levels and Caveats.)
Access Control is normally applied to individual Container records, and may beinherited by contained records or explicitly set for each contained record.
The SetAccessControlDetails method of the Record object is used to addspecifications of the Access Control for the record. This method requires that youspecify one of the six actions listed above and the access level (including thelocations, if private or ad-hoc.)
Visual Basic Example:
This example grants the following:
Public access to view the metadata
Inherited access to update the metadata
Only the Records Manager can delete the record.
! Note: that the connected user must have 'Modify Access Control' permissionfor this code to work.
Call objRecord.SetAccessControlDetails(dxViewRecord, asPublic)Call objRecord.SetAccessControlDetails(dxUpdateMetadata, asInherited)Call objRecord.SetAccessControlDetails(dxDeleteRecord, asPrivate,objTRIM.GetLocation("Records Manager"))
C# Example:
This example grants the following:
Public access to view the metadata
HP TRIM 6 Software Development Kit
Page 83
Inherited access to update the metadata
Only the Records Manager can delete the record.
! Note: that the connected user must have 'Modify Access Control' permissionfor this code to work.
objRecord.SetAccessControlDetails(dxRecordAccess.dxViewRecord,asAccessControlSettings.asPublic,null);
objRecord.SetAccessControlDetails(dxRecordAccess.dxUpdateMetadata,asAccessControlSettings.asInherited,null);
objRecord.SetAccessControlDetails(dxRecordAccess.dxDeleteRecord,asAccessControlSettings.asPrivate, db.GetLocation("Records Manager"));
HP TRIM 6 Software Development Kit
Page 84
Relationships
The context of a document in TRIM is generally provided by the Container file inwhich it is logically enclosed. To provide useful context for a Container file record,you can use various techniques such as a Classification system. You can alsoprovide context by creating relationships with other records in the Database. TRIMdefines some standard relationship types, but you can also create customrelationship definitions. Apart from the generic type of "related", all relationshiptypes in TRIM are transitive, meaning that the relationship has a subject and anobject (for example, the transitive relationship "A supersedes B" is not the same as"B supersedes A").
In the SDK, you use the Record object's AttachRelationship method to relate anotherrecord to the current record. The record on which the method is being called is thesubject of the relationship, and the other record (passed as an argument to themethod) is the object. The relationship type is determined by passing a value of therrRecordRelationship enumeration.
Visual Basic Example
This line of code creates a relationship of "Record A supersedes Record B".
objRecordA.AttachRelationship(objRecordB, rrDoesSupersede)
C# Example
This line of code creates a relationship of "Record A supersedes Record B".
objRecordA.AttachRelationship(objRecordB, rrRecordRelationship.rrDoesSupersede);
HP TRIM 6 Software Development Kit
Page 85
Record Locations
Defining relationships between a Container file and location objects (people andplaces) provides additional and useful context for the record.
Unlike record relationships, which can be user defined, you can only use TRIM'spredefined standard relationship types for record locations (and for contacts, seeRecord Contacts).
Record Locations represent actual (in the case of paper and other physical records)or logical (in the case of electronic records) places where a record resides. Everyrecord in TRIM has a property representing it's Current Location (where the record isnow) and another for it's Home Location (where the record should normally be orwhere it is to be returned.) There is also a property for Owner Location – the exactmeaning of this can vary according to the practises of each TRIM implementation,but normally represents the person or body that is responsible for the record. TheHome and Owner location of a record are typically derived from the default values foreach Record Type, but all record location properties can be set on creation of a newrecord or modified later.
The Record object has methods for setting or changing the value of these locationproperties, which allow the option of specifying the date & time of the change oflocation (the default is the current time.)
Visual Basic Example
This example sets the record's Home location to the unit called "Administration", andthe Current location to the connected user.
objRecord.SetHomeLocation(objTRIM.GetLocation("Administration"))objRecord.SetCurrentLocation(objTRIM.CurrentUser)
C# Example
This example sets the record's Home location to the unit called "Administration", andthe Current location to the connected user.
objRecord.SetHomeLocation(db.GetLocation("Administration"));objRecord.SetCurrentLocation(db.CurrentUser,DateTime.Now);
HP TRIM 6 Software Development Kit
Page 86
Record Contacts
Unlike record locations (see Record Locations), which tend to be internal units,Record Contacts are more commonly people or organisations that have a directassociation with the record, and may be internal or external to the organisation.Using the AttachContact method, TRIM allows each contact to be specificallyidentified as an Author, Addressee, Representative or Client. Other contactrelationship types must use the generic type of 'Other'.
Visual Basic Example
This example sets the record's Representative (and primary contact) to be theconnected user, and the Client to be the organisation called "My Organization".
objRecord.AttachContact(objTRIM.CurrentUser, ctRepresentative, True)objRecord.AttachContact(objTRIM.GetLocation("My Organization"), ctClient)' ctClient = Client
C# Example
This example sets the record's Representative (and primary contact) to be theconnected user, and the Client to be the organisation called "My Organization".
objRecord.AttachContact(db.CurrentUser, ctContactType.ctRepresentative,true,DateTime.Now);objRecord.AttachContact(db.GetLocation("My Organization"),ctContactType.ctClient,false,DateTime.Now);// ctClient = Client
HP TRIM 6 Software Development Kit
Page 87
Code Example - Visual Basic
This code demonstrates many of the features described above. The code will workwith the Demonstration Database provided on the TRIM installation disk.
Dim objTRIM As New DatabaseDim objRecord As RecordDim objRecordB As Record' Create a new File Folder recordSet objRecordType = objTRIM.GetRecordType("Research Project File")Set objRecord = objTRIM.NewRecord(objRecordType)With objRecord' Set keyword title and free text title
.GeneratedTitle = "Administration - Finance - Donations"
.TypedTitle = "Bequest from the estate of Lady Marchcroft"' Relate to the superseded recordSet objRecordB = objTRIM.GetRecord("76/915")Call .AttachRelationship(objRecordB, rrDoesSupersede)' Assign "Confidential" security level.SecLevel = objTRIM.GetSecurityLevel("Confidential")' Add "Research Projects" CaveatCall .AddCaveat(objTRIM.GetSecurityCaveat("Research Projects"))' Access Control - only this user can updateCall .SetAccessControlDetails(dxUpdateMetadata, asPrivate, objTRIM.CurrentUser)' LocationsCall .SetHomeLocation(objTRIM.GetLocation("Administration"))Call .SetCurrentLocation(objTRIM.CurrentUser)' ContactsCall .AttachContact(objTRIM.CurrentUser, ctAuthor, True)Call .AttachContact(objTRIM.GetLocation("Bay Books"), ctClient)' Verify and SaveIf Not .Verify Then
MsgBox .ErrorMessageElse
.SaveEnd If
End With
HP TRIM 6 Software Development Kit
Page 88
Code Example - C#
This code demonstrates many of the features described above. The code will workwith the Demonstration Database provided on the TRIM installation disk.
TRIMSDK.Database db = new TRIMSDK.Database();// Create a new File Folder recordTRIMSDK.RecordType objRecordType = db.GetRecordType("Research Project File");TRIMSDK.Record objRecord = db.NewRecord(objRecordType);// Set keyword title and free text titleobjRecord.GeneratedTitle = "Administration - Finance - Donations";objRecord.TypedTitle = "Bequest from the estate of Lady Marchcroft";// Relate to the superseded recordTRIMSDK.Record objRecordB = db.GetRecord("76/915");objRecord.AttachRelationship(objRecordB, rrRecordRelationship.rrDoesSupersede);// Assign "Confidential" security levelobjRecord.SecLevel = db.GetSecurityLevel("Confidential");// Add "Research Projects" CaveatobjRecord.AddCaveat(db.GetSecurityCaveat("Research Projects"));// Access Control - only this user can updateobjRecord.SetAccessControlDetails(dxRecordAccess.dxUpdateMetadata,asAccessControlSettings.asPrivate, db.CurrentUser);// LocationsobjRecord.SetHomeLocation(db.GetLocation("Administration"));objRecord.SetCurrentLocation(db.CurrentUser,DateTime.Now);// ContactsobjRecord.AttachContact(db.CurrentUser, ctContactType.ctAuthor, true,DateTime.Now);objRecord.AttachContact(db.GetLocation("Bay Books"),ctContactType.ctClient,false,DateTime.Now);
// Verify and Saveif (! objRecord.Verify(false)){
MessageBox.Show (objRecord.ErrorMessage);}else{
objRecord.Save();}
HP TRIM 6 Software Development Kit
Page 89
Creating a Document
This scenario describes the general processes for using the SDK to create a record ofa generic Record Type we are calling a 'Document'.(See Searching for Records - Creating a Container File).
While Container Files are usually created and maintained by specialist recordsmanagers, Documents, on the other hand, are usually created by end-users, andrequire little specific metadata other than the identification of the appropriateContainer File to which the Document belongs, as most other metadata and contextis inherited from the Container. A Document record usually consists of an electronicobject (the source document, image or other file), a unique identifier (which may beautomatically generated by TRIM), a record title and any other metadata required toprofile and index the record, and a pointer to the Container File from which thedocument derives its context.
The general steps for creating a new Document record are as follows:
1. Instantiate the appropriate Record Type object
2. Instantiate a new Record object of this Type
3. Identify the Container File for the document
4. Set the free text title
5. Attach an Electronic file
6. Assign the record's Author or other contacts (optional)
7. Set Access Control to the elecronic document (optional)
8. Assign other metadata or User Defined Fields (optional)
9. Save the Record object.
HP TRIM 6 Software Development Kit
Page 90
Titling and Numbering
Titling for documents is generally straightforward – free text titling is the norm, andthe title simply needs to succinctly describe the document or record. Recordnumbers may be assigned explicitly or they may be automatically generated – this isconfigured on the Record Type properties. If the number is explicitly assigned, thenumber (in expanded format) must be assigned to the LongNumber property (itmust be unique or the record will not be saved.)
Visual Basic ExampleobjRecord.Title = "Letter from executor regarding disbursements of Lady Marchcroft'sbequest"objRecord.LongNumber = "XK/008934"
C# ExampleobjRecord.Title = "Letter from executor regarding disbursements of Lady Marchcroft’sbequest";objRecord.LongNumber = "XK/008936";
HP TRIM 6 Software Development Kit
Page 91
Assigning to a Container
Although it is not compulsory, it is most common that an electronic record is logicallyassigned to a Container file that represents the subject matter, case, client file orother contextual grouping relevant to the document.
To assign a record to a Container, the existing Container record must be instantiated(by Id or URI) and then passed as an argument to the (contained) record object'sSetContainer method. The method includes a parameter for specifying whether therecord is also 'enclosed in' the Container, i.e. that the current location should reflectthat it is with the Container.
Visual Basic ExampleDim objContainer As RecordSet objContainer = objTRIM.GetRecord("76/915")objRecord.SetContainer(objContainer, True)
C# ExampleTRIMSDK.Record objContainer = db.GetRecord("76/915");objRecord.SetContainer(objContainer, true);
HP TRIM 6 Software Development Kit
Page 92
Attaching an Electronic Document
Document records can represent physical paper documents, but mostly they willinclude an electronic attachment, whether this is a word-processing document,scanned image or other type of file.
To attach an electronic document to a record, the file name and path must be usedto instantiate an InputDocument object. This object is then passed as an argumentto the record object's SetDocument method. The method includes parameters forspecifying whether this should replace any existing document (or be added as a newrevision), whether it should be marked as checked out to the current user, and anycomments to be added to the record's Notes field.
Visual Basic ExampleDim objDoc As New InputDocumentCall objDoc.SetAsFile("C:\myDocs\ThisFile.doc")Call objRecord.SetDocument(objDoc, False, False, "Created via SDK")
C# ExampleTRIMSDK.InputDocument objDoc = new InputDocument();// note that in C# the \ character is an escape symbol,// unless the string is preceded by an @.objDoc.SetAsFile(@"C:\myDocs\ThisFile.doc");objRecord.SetDocument(objDoc, false, false, "Created via SDK");
Alternatively, if the file to be attached is not known until run-time, you can call theSetDocumentUI method, which will display a dialog for the user to select the file.
Visual Basic ExampleIf Not objRecord.SetDocumentUI(hWnd, "TheDefault.doc", "Attach Document", False) Then
Msgbox "Action cancelled."Exit Sub
End If
C# Exampleint hWnd = Handle.ToInt32();if (! objRecord.SetDocumentUI(hWnd, "", "Attach Document", false)){
MessageBox.Show("Action cancelled.");}
HP TRIM 6 Software Development Kit
Page 93
Document Author
Record Contacts are TRIM location objects commonly representing people ororganisations that have a direct association with the record. The most common typeof Contact to be specified for an electronic document is the Author. Although theAttachContact method can be used for this and other contact types, a shortcut isprovided through the AuthorLoc property.
Visual Basic Example
This example sets the document's Author to be the connected user.
objRecord.AuthorLoc = objTRIM.CurrentUser
C# Example
This example sets the document's Author to be the connected user.
objRecord.AuthorLoc = db.CurrentUser;
HP TRIM 6 Software Development Kit
Page 94
Access Control for Documents
For more information on this subject, see Searching for Records - Access Control.
The SetAccessControlDetails method of the Record object is used to addspecifications of the Access Control for the record. This method requires that youspecify one of the six actions listed above and the access level (including thelocations, if private or ad-hoc.) For Document records, the typical action is to assignView and Update rights to the electronic document.
Visual Basic Example
This example grants the following:
Private access to the connected user for updating the electronic document
Public access to view the Document.
Call objRecord.SetAccessControlDetails(dxUpdateDocument, asPrivate, objTRIM.CurrentUser)Call objRecord.SetAccessControlDetails(dxViewDocument, asPublic)
C# Example
This example grants the following:
Private access to the connected user for updating the electronic document
Public access to view the Document.
objRecord.SetAccessControlDetails(dxRecordAccess.dxUpdateDocument,asAccessControlSettings.asPrivate, db.CurrentUser);objRecord.SetAccessControlDetails(dxRecordAccess.dxViewDocument,asAccessControlSettings.asPublic,null);
HP TRIM 6 Software Development Kit
Page 95
Setting User-Defined Fields
Any type of record can have any number of User Defined Fields associated with it.(For background information on User Defined Fields, see Object Properties - TheFieldDefinition Object)
To assign values to User Defined Fields on a record, you must instantiate aFieldDefinition object representing the User Defined Field, and pass this and aVariant containing the data value to the Record object's SetUserField method.
Visual Basic Example
This example assumes that a User Defined String Field called "Job Code" has beencreated in TRIM. It assigns a value of "D0933" to this field on the current record.
Call objRecord.SetUserField(objTRIM.GetFieldDefinition("Job Code"), "D0933")
C# Example
This example assumes that a User Defined String Field called "Job Code" has beencreated in TRIM. It assigns a value of "D0933" to this field on the current record.
objRecord.SetUserField(db.GetFieldDefinition("Job Code"), "D0933");
HP TRIM 6 Software Development Kit
Page 96
Creating a Record with user input
Code Example – Visual Basic' Modular level (m_)Private m_TRIMDatabase As TRIMSDK.Database
' Procedural level variables (p_)Dim p_RecordTypes As TRIMSDK.RecordTypesDim p_RecordType As TRIMSDK.RecordTypeDim p_NewRecord As TRIMSDK.Record
' Instantiate a collection of Record Types.Set p_RecordTypes = m_TRIMDatabase.MakeRecordTypes' Fill the collection with all Record Types, before filteringp_RecordTypes.SelectAll' Instantiate a Record Type by choosing it from the collectionSet p_RecordType = p_RecordTypes.ChooseOneUI(hWnd)If p_RecordType Is Nothing Then
Debug.Print "User pressed Cancel"Exit Sub
End If' Instantiate a new Record of the Record Type passed in.Set p_NewRecord = m_TRIMDatabase.NewRecord(p_RecordType)' Display the properties of new Record' Returns True if the user selects OK.If p_NewRecord.PropertiesUI(hWnd) Then
If p_NewRecord.Verify Thenp_NewRecord.SaveMsgBox "Created a new record - " & p_NewRecord.Number
ElseMsgBox "Error saving new Record properties " & _p_NewRecord.ErrorMessage,
vbExclamationEnd If
End If' Clean UpSet p_RecordTypes = NothingSet p_RecordType = NothingSet p_NewRecord = Nothing
HP TRIM 6 Software Development Kit
Page 97
Code Example – C#
private TRIMSDK.Database db = new TRIMSDK.Database();// Instantiate a collection of Record Types.TRIMSDK.RecordTypes recordTypes = db.MakeRecordTypes();// Fill the collection with all Record Types, before filteringrecordTypes.SelectAll();// Instantiate a Record Type by choosing it from the collectionint hWnd = Handle.ToInt32();TRIMSDK.RecordType recordType = recordTypes.ChooseOneUI(hWnd);if (recordType == null){
Console.WriteLine( "User pressed Cancel");return;
}// Instantiate a new Record of the Record Type passed in.TRIMSDK.Record newRecord = db.NewRecord(recordType);// Display the properties of new Record// Returns True if the user selects OK.if (newRecord.PropertiesUI(hWnd)){
if (newRecord.Verify(false)){
newRecord.Save();MessageBox.Show( "Created a new record - " + newRecord.Number);
}else{
MessageBox.Show( "Error saving new Record properties " +newRecord.ErrorMessage, "", MessageBoxButtons.OK,MessageBoxIcon.Exclamation);
}}// Clean UprecordTypes = null;recordType = null;newRecord = null;
HP TRIM 6 Software Development Kit
Page 98
Creating a Record with no user input
Code Example – Visual Basic
' Modular level (m_)Private m_TRIMDatabase As TRIMSDK.Database
' Procedural level variables (p_)Dim p_RecordTypes As TRIMSDK.RecordTypesDim p_RecordType As TRIMSDK.RecordTypeDim p_NewRecord As TRIMSDK.Record
Set m_TRIMDatabase = New TRIMSDK.DatabaseOn Error GoTo err_handler'// Instantiate a Record Type from its name or UriSet p_RecordType = m_TRIMDatabase.GetRecordType("Research Project File")If p_RecordType Is Nothing Then
'// Name or Uri did not uniquely identify a record type.Debug.Print "Error instantiating Record Type."Exit Sub
End IfSet p_HomeLocation = m_TRIMDatabase.GetLocation("Llewellyn, Brian (Professor) OBE")If p_HomeLocation Is Nothing Then
'// Name or Uri did not uniquely identify a TRIM Location.Debug.Print "Error instantiating Location: " & p_RecordType.ErrorMessageExit Sub
End If'// Instantiate a new Record of the Record Type passed in.Set p_NewRecord = m_TRIMDatabase.NewRecord(p_RecordType)'// Complete all of the new record's properties.With p_NewRecord
'// An error is raised if any of these properties fail.'// Thesaurus titling.GeneratedTitle = "ADMINISTRATION - FINANCE - LEASES AND RENTAL AGREEMENTS -
SUPPLIER [Larger than Life Ventures]"' p_Keyword.Name'// Free text titling.TypedTitle = "New Record Title"'// Record's Home location.SetHomeLocation p_HomeLocationIf p_NewRecord.Verify Then
p_NewRecord.SaveDebug.Print "Created a new record - " & p_NewRecord.Number
ElseMsgBox "Error saving new Record" & p_NewRecord.ErrorMessage, vbExclamation
End IfEnd With
Set p_RecordType = NothingSet p_NewRecord = NothingSet p_HomeLocation = NothingExit Sub
err_handler:'// The error message is also populated in the Err object.MsgBox "Error: " & Err.Description, vbExclamation
Set p_RecordType = NothingSet p_NewRecord = NothingSet p_HomeLocation = Nothing
HP TRIM 6 Software Development Kit
Page 99
Code Example – C#
TRIMSDK.Database db = new TRIMSDK.Database();try{
// Instantiate a Record Type from its name or UriTRIMSDK.RecordType recordType = db.GetRecordType("Research Project File");if (recordType == null){
// Name or Uri did not uniquely identify a record type.Console.WriteLine ("Error instantiating Record Type.");return;
}TRIMSDK.Location homeLocation = db.GetLocation("Llewellyn, Brian (Professor)
OBE");if (homeLocation == null){
// Name or Uri did not uniquely identify a TRIM Location.Console.WriteLine( "Error instantiating Location: " +
recordType.ErrorMessage);return;
}// Instantiate a new Record of the Record Type passed in.TRIMSDK.Record newRecord = db.NewRecord(recordType);// Complete all of the new record's properties.// An error is raised if any of these properties fail.// Thesaurus titlingnewRecord.GeneratedTitle = "ADMINISTRATION - FINANCE - LEASES AND RENTAL
AGREEMENTS - SUPPLIER [Larger than Life Ventures]"; //p_Keyword.Name// Free text titlingnewRecord.TypedTitle = "New Record Title";// Record's Home locationif (newRecord.Verify(false)){
newRecord.Save();Console.WriteLine( "Created a new record - " + newRecord.Number);
}else{
MessageBox.Show( "Error saving new Record" +newRecord.ErrorMessage,"",MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
}recordType = null;newRecord = null;homeLocation = null;return;
}catch(Exception ex){
// The error message is also populated in the ex object.MessageBox.Show( "Error: " + ex.Message, "", MessageBoxButtons.OK,
MessageBoxIcon.Exclamation);}
HP TRIM 6 Software Development Kit
Page 100
Checking Out a Document
When an electronic document in TRIM needs to be updated, it must first be checkedout to a user, to prevent others from attempting to edit the same document. Oncompletion of the changes, it can be check-in to make the updated version availablein TRIM.
Locating the Document
Various methods can be used to locate and instantiate the document that is to bechecked out. If the unique identifier (Record Number or URI) is known, it can bepassed to the Database object's GetRecord method. Alternatively the record can belocated by the user, either through an interactive search or by selecting from thecontents of a specific Container file.
Visual Basic Example
This example combines some elements of the options described above, by using aRecords collection to display the contents of a specific Container file, andinstantiating the record that the user selects from a displayed result list.
Dim objContainer As RecordDim objDoc As RecordDim colContents As RecordsSet objContainer = objTRIM.GetRecord("96/715")Set colContents = objTRIM.MakeRecordsCall colContents.SelectContentsOf(objContainer)Set objDoc = colContents.ChooseOneUI(hWnd)If Not objDoc.IsElectronic Then
Exit SubEnd If
C# Example
This example combines some elements of the options described above, by using aRecords collection to display the contents of a specific Container file, andinstantiating the record that the user selects from a displayed result list.
TRIMSDK.Record objContainer = db.GetRecord("96/715");TRIMSDK.Records colContents = db.MakeRecords();colContents.SelectContentsOf(objContainer);int hWnd = Handle.ToInt32();TRIMSDK.Record objDoc = colContents.ChooseOneUI(hWnd);if ( objDoc != null && ! objDoc.IsElectronic){
return;}
HP TRIM 6 Software Development Kit
Page 101
Check Out Options
Once the appropriate electronic document has been identified and instantiated, theobject can be programmatically checked out to a specific file destination by callingthe GetDocument method.
Visual Basic ExampleIf objDoc.IsElectronic Then
Call objDoc.GetDocument("C:\tmp\MyFile.doc", True, "Checked out via SDK")End If
C# Exampleif (objDoc.IsElectronic){
objDoc.GetDocument(@"C:\tmp\MyFile.doc", true, "Checked out via SDK", " ");}
Alternatively, a user can choose a document to check out to their TopDrawer via adialog by calling TopDrawerDisplayUI on a collection of records.
Visual Basic Example
In this example, the user selects from their list of favorite documents.
Call colRecords.SelectFavoritesCall colRecords.TopDrawerDisplayUI(hWnd)
C# Example
In this example, the user selects from their list of favorite documents.colRecords.SelectFavorites();
int hWnd = Handle.ToInt32();colRecords.TopDrawerDisplayUI(hWnd);
HP TRIM 6 Software Development Kit
Page 102
Check In
After a document has been edited and it is ready to be returned to TRIM, it must beChecked-in. This can be done manually either through the TRIM or TopDrawerclients (if the document was checked out to TopDrawer.) To Check-in a documentprogrammatically, you must use the SetDocument method of the record that hasbeen checked-out. The method provides options for adding notes and specifyingwhether the latest revision should replace the current one or be stored as a newrevision.
Visual Basic ExampleIf objDoc.CheckedOutTo.Uri = objTRIM.CurrentUser.Uri Then
objDoc.SetDocument("C:\tmp\MyFile.doc", True, False, "Checked in via SDK")End If
C# Exampleif (objDoc.CheckedOutTo.Uri == db.CurrentUser.Uri){
TRIMSDK.InputDocument document = new InputDocument();document.SetAsFile(@"C:\myDocs\ThisFile.doc");objDoc.SetDocument(document, true, false, "Checked in via SDK");
}
To check-in a document interactively, you can use the SetDocumentUI method. Thiswill display a TRIM dialog to allow the user to specify the check-in options.
Visual Basic ExampleIf Not SetDocumentUI(hWnd, "MyFile.doc", "Check-In", False) Then
MsgBox "Check-in cancelled"End If
C# Exampleint hWnd = Handle.ToInt32();if (! objDoc.SetDocumentUI(hWnd, "", "Check-In", false)){
MessageBox.Show("Check-in cancelled");}
HP TRIM 6 Software Development Kit
Page 103
Working with Locations
The Location object is an encapsulation of all properties and methods associated withPersons, Organizations, Positions and Groups. Locations can be identified by nameor by URI, and can be selected on other criteria, such as date of birth, nicknames, ormembership of a particular organization, role or group.
Finding a Person by Name
Although the names of non-persons (Units, Positions and Organizations) must beunique, this is not the case for persons (Staff Names & Contacts). However, TRIMallows you to store a 'nickname' for any person, and this can be used as a substitutefor a persons name when searching.
To find a particular person by name, you must pass the person's combined name andtitle to the Database object's GetLocation method.
Visual Basic ExampleDim objLoc As LocationSet objLoc = objTRIM.GetLocation("Abbott, Peter (Mr)")
C# ExampleTRIMSDK.Location objLoc = db.GetLocation("Abbott, Peter (Mr)");
Alternatively, you can pass a sub-string of the person's name followed by a wildcard(asterisk) character, as long as the text provided uniquely identifies a location.
Visual Basic ExampleSet objLoc = objTRIM.GetLocation("Abbott, P*")Set objLoc = objTRIM.GetLocation("Abbott*")Set objLoc = objTRIM.GetLocation("Abbott, Peter*")
C# ExampleobjLoc = db.GetLocation("Abbott, P*");objLoc = db.GetLocation("Abbott*");objLoc = db.GetLocation("Abbott, Peter*");
If the sub-string does not uniquely identify a location (i.e. there are no matches, orthere is more than one match) then a null object will be returned.
Visual Basic ExampleSet objLoc = objTRIM.GetLocation("Abb*") ' finds Abbott and AbbeyIf objLoc Is Nothing Then Exit Sub
C# ExampleobjLoc = db.GetLocation("Abb*"); //finds Abbott and Abbeyif (objLoc == null){
return;}
HP TRIM 6 Software Development Kit
Page 104
Creating a New Staff Member
To create a new staff member, you must instantiate a new location by calling theNewLocation method on the Database object. You then define the type of thelocation by assigning a value (in this case lcPerson) to the LocType property. Youcan then set various properties representing the person's name, contact details suchas telephone numbers and addresses, administrative details such as employee IDnumbers and so on.
If the new person is to be a TRIM user, then there are login and security details to beprovided. You will need to specify the user's network login ID and optionally anexpiry date. For the security profile, you are required to either explicitly state theuser's Security Level (and optionally any Caveats) and a user category, or if role-based security is used you can specify that the user takes the profile of a predefinedgroup or user.
Relationships such as membership of units or reporting lines are created using theAddRelationship method and passing parameters for the related location and therelationship type.
Addresses (including electronic addresses such as email or URL) are added by callingthe New method on the LocAddresses or LocEAddresses collection properties.
HP TRIM 6 Software Development Kit
Page 105
Code Example – Visual Basic
Dim objUnit As LocationDim objBoss As LocationDim objPeer As LocationDim objRole As LocationDim objSec As SecurityLevelDim objEmail As LocEAddressDim bRoleSecurity As Boolean
bRoleSecurity = FalseSet objRole = objTRIM.GetLocation("Project Manager")
Set objLoc = objTRIM.NewLocationWith objLoc
.LocType = lcPerson
' Name.Surname = "Evans".GivenNames = "David".Initial1 = "D".Initial2 = "W".Honorific = "Mr"
' Personal & Administrative.IsWithin = True ' Internal to the org.IdNumber = 793906.ReviewDate = Date + 365.DateOfBirth = #11/29/1966#.PhoneNo = "555 123496".MobileNo = "+44 7939 062736".Notes = "Created via SDK"
' Login details.CanLogin = True.LoginExpires = Date + (365 * 3) ' Valid for 3 years.LogsInAs = "evans" ' Network login id
' SecurityIf bRoleSecurity Then
.UseProfileOf = objRoleElse
Set objSec = objTRIM.GetSecurityLevel("Confidential").SecLevel = objSec.UserType = utRecordsWorker
End If
' Email addressSet objEmail = .LocEAddresses.NewobjEmail.EAddressType = etMailobjEmail.EAddress = "[email protected]"objEmail.Description = "Default business email"
' RelationshipsCall .AddRelationship(objRole, lrHasGroups)Set objUnit = objTRIM.GetLocation("Administration")Call .AddRelationship(objUnit, lrMemberOf, True)Set objBoss = objTRIM.GetLocation("Neumann, Ilse*")Call .AddRelationship(objBoss, lrBossedBy)
' Confirm & SaveIf .Verify(True) Then
.SaveMsgBox .FormattedName & " created."
ElseMsgBox .ErrorMessage
End IfEnd With
HP TRIM 6 Software Development Kit
Page 106
Code Example – C#
bool bRoleSecurity = false;TRIMSDK.Location objRole = db.GetLocation("Project Manager");TRIMSDK.Location objLoc = db.NewLocation();objLoc.LocType = lcLocationType.lcPerson;
// NameobjLoc.Surname = "Evans";objLoc.GivenNames = "David";objLoc.Initial1 = "D";objLoc.Initial2 = "W";objLoc.Honorific = "Mr";
// Personal & AdministrativeobjLoc.IsWithin = true; // Internal to the orgobjLoc.IdNumber = Convert.ToString(793906);objLoc.ReviewDate = DateTime.Today.AddYears(1);DateTime dob = new DateTime(1966,11,29);objLoc.DateOfBirth = dob;objLoc.PhoneNo = "555 123496";objLoc.MobileNo = "+44 7939 062736";objLoc.Notes = "Created via SDK";
// Login detailsobjLoc.CanLogin = true;objLoc.LoginExpires = DateTime.Today.AddYears(3); // Valid for 3 yrsobjLoc.LogsInAs = "evans"; // Network login id
// Securityif (bRoleSecurity){
objLoc.UseProfileOf = objRole;}else{
TRIMSDK.SecurityLevel objSec = db.GetSecurityLevel("Confidential");objLoc.SecLevel = objSec;objLoc.UserType = utUserTypes.utRecordsWorker;
}
// Email addressTRIMSDK.LocEAddress objEmail = objLoc.LocEAddresses.New();objEmail.EAddressType = etEAddressType.etMail;objEmail.EAddress = "[email protected]";objEmail.Description = "Default business email";
// RelationshipsobjLoc.AddRelationship(objRole, lrLocRelationshipType.lrHasGroups,false);TRIMSDK.Location objUnit = db.GetLocation("Administration");objLoc.AddRelationship(objUnit, lrLocRelationshipType.lrMemberOf, true);TRIMSDK.Location objBoss = db.GetLocation("Neumann, Ilse*");objLoc.AddRelationship(objBoss, lrLocRelationshipType.lrBossedBy,false);
// Confirm & Saveif (objLoc.Verify(true)){
objLoc.Save();MessageBox.Show( objLoc.FormattedName + " created.");
}else{
MessageBox.Show( objLoc.ErrorMessage);}
HP TRIM 6 Software Development Kit
Page 107
Reference
Objects
As of TRIM 6.1, the reference section detailing the methods and properties of eachTRIM SDK object has been replaced by helpstrings which appear in the objectbrowser of your chosen Integrated Development Environment. These helpstringscontain the most up-to-date information about each method and property in the HPTRIM SDK.
ActiveX Controls
The controls are contained in a component called "HP TRIM ActiveX Controls" andimplemented by the file "tsjOCX.dll"; the methods and properties are defined in theType Library "TRIMOCXLib".
To use these ActiveX controls in a Microsoft Visual Basic project assuming your editoris Microsoft Visual Studio, select Project | Components from the menu and ensurethat the check box against "HP TRIM ActiveX Controls" is checked.
Document Viewer - TRIMviewer
The TRIMviewer is a control that can view documents of a range of file types. It isused in HP TRIM to display electronic documents attached to TRIM records. It doesnot require the native application to function. It is for display only so the documentdisplayed cannot be edited, though it can be printed. There are a number ofoccasions where such a viewer is useful.
Confirmation, if a user is about to check out a document for editing or about to savea document into TRIM from a directory, providing the ability to view the documentprior to executing the operation can be useful.
Resource tool, there might be a need for a user to see information that is on anelectronic document attached to a TRIM record (for example, A Client contract sothat when a client calls the help line the help officer can lookup the client file and seethe contract).
HP TRIM 6 Software Development Kit
Page 108
Properties
Name Description
CanSaveOrLaunchCurrentActivates the SaveCurrent and LaunchCurrentmethods
DocFormat Format of the viewer document
Enabled Whether the window is enabled for input.
Font Control font
MenuHandle HMENU handle.
PermitLaunchReturns/sets the ability to launch the viewersfile in its native application
StatusTextReturns a number that indicates whichmessage is to be displayed given that theviewer cannot view the selected file.
TextReturns/Sets a string that is displayed in theTRIMviewer control when there is no filecurrently being displayed.
HP TRIM 6 Software Development Kit
Page 109
CanSaveOrLaunchCurrent
If true, the methods TRIMViewer.SaveCurrent and TRIMViewer.LaunchCurrent willfunction.
If false, these methods will do nothing.
SyntaxTRIMviewer.CanSaveOrLaunchCurrent = [Boolean]
HP TRIM 6 Software Development Kit
Page 110
DocFormat (Read Only)
The format of the document known to the viewer via the View method.
Syntax[vwDocFormat ] = TRIMviewer.DocFormat
HP TRIM 6 Software Development Kit
Page 111
Enabled
Returns/sets a value that determines whether an object can respond to user-generated events.
SyntaxTRIMviewer.Enabled = [Boolean]
HP TRIM 6 Software Development Kit
Page 112
Font
Font used by the control.
SyntaxTRIMviewer.Font = [stdole.IfontDisp ]
HP TRIM 6 Software Development Kit
Page 113
MenuHandle (Read Only)
HMenu Handle to a menu, usually a Right Mouse Button menu
Syntax[Boolean] = TRIMviewer.MenuHandle
HP TRIM 6 Software Development Kit
Page 114
PermitLaunch
Returns/Sets a boolean value that determines if the native application is to belaunched when the viewer is unable to view an electronic file.
SyntaxTRIMviewer.PermitLaunch = [Boolean]
HP TRIM 6 Software Development Kit
Page 115
StatusText (Read Only)
Returns a number that indicates which message is to be displayed given that theviewer cannot view the selected file.
Syntax[Long] = TRIMviewer.StatusText
HP TRIM 6 Software Development Kit
Page 116
Text
Returns/Sets a string that is displayed in the TRIMviewer control when there is nofile currently being displayed.
SyntaxTRIMviewer.Text = [String]
HP TRIM 6 Software Development Kit
Page 117
Methods
Name Description
CanView Determines if the viewer is able to view the file
Copy Copy Selection to the Clipboard
Clear Clears the current file from the viewer
DoMenu For internal use only
EnableMenu For internal use only
LaunchCurrentLaunch a copy of the current document in the associatedapplication
Print Prints the defined file
PrintCurrent Prints the file that the viewer is currently viewing
View Views the defined file
HP TRIM 6 Software Development Kit
Page 118
CanView
Tests the entered file and returns true if the viewer can display this file.
Syntax[Boolean] = TRIMviewer.CanView (fileName As String, stream As Unknown)
Parameters
Name Type Default Description
Filename String The path and file name of the file to beviewed
Stream Unknown For internal use only. In VB use thereserved word "Nothing" as the value forstream
Return Value
Type Description
Boolean Returns true if it is possible for the viewer to view the file
HP TRIM 6 Software Development Kit
Page 119
Copy
Copy Selection to the Clipboard.
SyntaxTRIMviewer.Copy ()
HP TRIM 6 Software Development Kit
Page 120
Clear
If the viewer is currently viewing a file using this method will clear the reference tothis file. The TRIMviewer will then be blank.
SyntaxTRIMviewer.Clear ()
HP TRIM 6 Software Development Kit
Page 123
LaunchCurrent
Launches a copy of the current document using the associated application instead ofthe TRIMViewer.
! Note: The method does not allow changes to be made to the document whilelaunched in the associated application. The document is saved to a temporarydirectory as a read-only file which is then opened for viewing with the associatedapplication. The temporary file is deleted when TRIM is closed down.
SyntaxTRIMviewer.LaunchCurrent ()
HP TRIM 6 Software Development Kit
Page 124
Prints the nominated file, deleting the file if it is marked as a tempfile and showing aprint dialog if desired.
SyntaxTRIMviewer.Print (fileName As String, tempFile As Boolean, stream As Unknown, showDialogsAs Boolean)
Parameters
Name Type Default Description
filename String The path and file name of the file to beviewed
tempFile Boolean Indicates if the file is to be deleted once thefile is printed. Set this value to false if youdo not want the nominated file to be deletedas part of this process.
stream Unknown For internal use only. In VB use thereserved word "Nothing" as the value forstream.
showDialogs Boolean Indicates if a print dialog (user interface) isto be displayed prior to printing. Set thisvalue to true to display the dialog.
HP TRIM 6 Software Development Kit
Page 125
PrintCurrent
Prints the file that is currently being viewed, showing a print dialog if desired.
SyntaxTRIMviewer.PrintCurrent (showDialogs As Boolean)
Parameters
Name Type Default Description
showDialogs Boolean Indicates if a print dialog (user interface) is tobe displayed prior to printing. Set this value totrue to display the dialog.
HP TRIM 6 Software Development Kit
Page 126
View
The primary method on the TRIMviewer control, it is used to display the nominatedfile. If it is marked as a temp file, it will delete the file when a new file is viewed, theclear method is called or the control destroyed.
Syntax[Boolean] = TRIMviewer.View (fileName As String, tempFile As Boolean, stream As Unknown,launched As Boolean)
Parameters
Name Type Default Description
Filename String The path and file name of the file to be viewed
tempFile Boolean Indicates if the file is to be deleted when it is nolonger viewed. Set this value to false if you donot want the nominated file to be deleted as partof this process.
Stream Unknown For internal use only. In VB use the reservedword "Nothing" as the value for stream
launched Boolean Is a Return Value (so you must supply a variableof type Boolean) see the Return Value table(below) for its use
Return Value
Type Description
Boolean Returns true if the view was successful
launchedReturns true if the viewer could not display the file and solaunched the associated application
HP TRIM 6 Software Development Kit
Page 127
Events
Name Description
ViewOccurs when an object inside the file being viewed isdouble clicked
HP TRIM 6 Software Development Kit
Page 128
View
If the file being viewed has an embedded or contained object and the user doubleclicks it the view event occurs (for example, The file bing viewed is a zip file and oneof the compressed files is double clicked, you could capture this event to launch orview the compressed file).
SyntaxTRIMviewer.View (fileName As String, displayName As String, deleteAfter As Boolean,handled As Boolean)
Parameters
Name Type Default Description
filename String The path and file name of the file embedded orcontained file
displayName String The name of the embedded or contained file
deleteAfter Boolean True Used to determine if the temporary file that isthe embedded or contained file is to be deletedafter this event. Set this to false if you do notwant the file to be deleted at the end of thisprocedure.
handled Boolean False Used to indicate if this event has been handled.Setting this to True will indicate that theTRIMviewer does not need to do anything atthe completion of this event. Setting this totrue will mean that the deleteAfter setting isignored.
HP TRIM 6 Software Development Kit
Page 129
Edit Box - TRIMedit
The TRIM Edit box is a combination control that is used through out HP TRIM. Itconsits of a text area and a button know in TRIM 5 and 6 as a KwikSelect. It alsocontains a calander for date selection as well as some common windows dialogs forselecting a file or directory. The button can also be used to launch a spelling checkon the text in the text area of the control. It is a versatile control that can save asigificant amount of code writing.
More information on using the TRIMedit control
The following table indicates the Mode that the TRIMedit control is in along with apicture of the control a description and any additional controls used in the selectedMode.
Mode Picture ConstituantControls
Description
Browse None Fires the controls Browseevent that theprogrammer can code to(for example, the browseevent could contain codeto do a record lookup.When the user hasselected a record therecords number can beentered in the text areaof the control. Theselected records Uri canbe stored in the controlsUri property).
SpellCheck
HP TRIMSpell CheckControl
When the Spell Checkbutton is clicked the HPTRIM Spell Check controlis launched and the textin the control is checked(for example, Great for anotes field).
SelectDirectory
BrowseFolderControl
When the Folder buttonis clicked a Browse Foldercontrol is displayed andwhen a folder is selectedthe full path to theselected folder is enteredin the text area of thecontrol.
Input File File OpenControl
When selected a FileOpen dialog is displayedto assist the user inselecting an existing file
HP TRIM 6 Software Development Kit
Page 130
from the file system.
OutputFile
Save AsControl
When selected a Save Asdialog is displayed. Theuser can browse to thedesired directory andenter the file name theywant to use. When saveis selected the full pathand file name areentered in the text areaof the control.
! Note: this does notsave the file. Theprogrammer wouldgenerally use theBrowseSelected event ifthey wanted to save afile at this time.
Date andTime
CalanderControl
When selected aCalander control isdisplayed to assist theuser in selecting a date.If any canned dates aresupported(CannedDatesModeproperty on the TRIMeditcontrol) the drop downlist on the calandercontrol will be populatedwith the supportedvalues. The Date orcanned date will then beentered in the date areaof the control.
Date CalanderControl
Same as the Date andTime description above.The difference beingthere is no area to storethe time value.
Format None Same as the Browsemode where theprogrammer must usethe Browse event to runany functionality theywant when the button onthe TRIMedit control isselected.
HP TRIM 6 Software Development Kit
Page 131
! Note: The BrowseSelected event is fired when control is returned to theTRIMedit control from any constituent controls. This can be used by theprogrammer to do any additional function/s required by the program (forexample, when using in Select Directory mode the programmer could validate ifthe current user has appropriate permissions on the selected folder. Or whenusing in Output File mode the programmer could attempt to save the file withthe user entered file name).
HP TRIM 6 Software Development Kit
Page 132
Constituent Controls
Name Picture
Spell Check
File OpenControl
HP TRIM 6 Software Development Kit
Page 134
Browse FolderControl
As you can see the TRIMedit control can be a powerful tool to get requiredfunctionality into your program fast.
HP TRIM 6 Software Development Kit
Page 135
Property Pages
The TRIMedit Control has the following property pages to assist the developer insetting up the control.
! Note: Not all properties of the TRIMedit control are relevant in all SelectModes (for example, the Force Spell Check property on the Verification page isnot relevant when the Mode is set to Date).
HP TRIM 6 Software Development Kit
Page 136
General
Name on Property page TRIMedit controlproperty
Type
Select Mode SelectMode ksSelectMode
Scroll Bars ScrollBars ksScrollMode
History Limit HistoryLimit Long
Visible History HistoryVisibleRows Long
Window Text Text String
Browse State BrowseState ksBrowseMode
History Registry Key HistoryKey String
Numbers Only Number Boolean
Password PassWord Boolean
Border Border Boolean
Locked Locked Boolean
Multiline MultiLine Boolean
Want Return WantReturn Boolean
HP TRIM 6 Software Development Kit
Page 137
Verification
Name on Property page TRIMedit controlproperty
Type
Canned Date Mode CannedDatesMode ksCannedDatesMode
Allow Blank AllowBlank Boolean
Allow Blank Time AllowBlankTime Boolean
Allow Overwrite AllowOverwrite Boolean
Maximum Length MaxLength Long
Allow Create AllowCreate Boolean
Confirm Overwrite ConfirmOverwrite Boolean
Force Spell Check ForceSpellCheck Boolean
HP TRIM 6 Software Development Kit
Page 138
Fonts
Name on Property page TRIMedit controlproperty
Type
All fields on the Fontspage
FontifontDisp
The fonts page is provided to assist the programmer in setting the attributes of thefont property.
HP TRIM 6 Software Development Kit
Page 139
Properties
Name Control Modes that usethis property
Description
AllowBlankAll Allow the text area of the
control to be blank
AllowBlankTimeDate and Time Allow the Time section of
the control when in Dateand Time mode to be blank
AllowCreateSelect Directory, OutputFile
Allows the creation ofdirectorys
AllowOverwriteOutput File Allows a file selected by
the user via the
BorderAll Indicates if the control has
a boarder or appears flat
BrowseStateAll Returns/Sets the state (for
example,. Disabled of thebutton on the control)
CannedDatesModeDate, Date and Time Returns/Sets which if any
canned dates aresupported
CanUndoAll Enables the Edit Undo
menu and function
CaptionWindow
Windows Handle (HWnd)to a static control that isconsidered the caption forthis edit
ConfirmOverwrite
All Dependent on the state ofthe AllowOverwriteproperty, will prompt theuser to confirm a fileoverwrite
CurSelAll Returns/Sets the index of
the item selected on thedropdown list
CursorPositionAll Returns/sets the cursor
position in the text area ofthe control as a number
DateTimeDate, Date and Time Returns/sets the Date or
DateTime
HP TRIM 6 Software Development Kit
Page 140
Enabled
Returns/sets a value thatdetermines whether anobject can respond touser-generated events.
ExtraTextAll Returns/sets any extra text
for use in tool tips
ExtraTextInListAll Returns/sets any extra text
for use in tool tips when onthe list
FileFilter
Input File, Output File String representing the filetypes used by the Save Asor Open constituantcontrols
FontAll The font used in the text
area of the control
ForceSpellCheck
Browse, Spell Check Returns/Sets the valuethat determines if aspelling check must beperformed on the string inthe text area of the control
HistoryCountAll Returns/sets the number
of history items for thecontrol
HistoryKey
All Returns/sets the registrykey used when saving orloading the historycollection
HistoryLimitAll Returns/sets the maximum
number of history itemsthe control will store
HistoryVisibleRowsAll Returns/Sets the number
of visible history rows
HistoryWhenLocked
All Returns/Sets whether theHistory dropdown willfunction even if the controlis locked
ItemCountAll Returns the number of
non-history items in thedropdown list
LockedAll Returns/Sets an indicater
as to whether the text area
HP TRIM 6 Software Development Kit
Page 141
of the control is locked
MaxLength
All Returns/Sets themaximum length of text auser can enter into the textarea of the control
Modified
All Returns true if the value inthe text area of the controlhas changed after loadingthe control
MultiLine
All Returns/Sets the switchthat determines if text inthe text area of the controlcan span more than oneline
Number
All Returns/Sets the switchthat determines if numbersare the only values theuser is allow to enter in thetext area of the control
PassWord
All Returns/Sets the switchthat determines if thevalue in the text area willbe masked. Ignored if thecontrol is set to supportmultiple lines
ScrollBarsAll Indicates if scroll bars will
be displayed in the textarea of the control
SelectModeN/A Returns/Sets the mode of
the control
SelectOnFocus
All Returns/Sets a value thatdetermines if the text inthe text area of the controlgets selected when thecontrol gets focus
TextAll Returns/sets the value in
the text area of the control
ToolTipsAll Returns/sets the value
indicating if the control canhave a tool tip
UriAll Returns/Sets a TRIM Uri
value such as the Uri of arecord whose number is
HP TRIM 6 Software Development Kit
Page 142
being displayed in the textarea of the control
ValidatedAll Returns/sets the valid
state of the information inthe text area of the control
WantReturn
Allows (if true) the user toinsert carriage returns withthe ENTER key within amultiline TRIMedit box
AllowBlank
Returns/Sets a value that determines if the control can be valid even if the text areaof the control is blank.
SyntaxTRIMedit.AllowBlank = [Boolean]
HP TRIM 6 Software Development Kit
Page 143
AllowBlankTime
Allow the Time section of the control when in Date and Time mode to be blank.
SyntaxTRIMedit.AllowBlankTime = [Boolean]
HP TRIM 6 Software Development Kit
Page 144
AllowCreate
Enables the control to create a file system directory or folder when required.
SyntaxTRIMedit.AllowCreate = [Boolean]
HP TRIM 6 Software Development Kit
Page 145
AllowOverwrite
Enables the control to overwrite an existing file where required.
SyntaxTRIMedit.AllowOverwrite= [Boolean]
HP TRIM 6 Software Development Kit
Page 146
Border
Detirmines if the control will be displayed with a boarder (3D) or without (flat).
SyntaxTRIMedit.Border= [Boolean]
HP TRIM 6 Software Development Kit
Page 147
BrowseState
Returns/Sets the active state of the control.
SyntaxTRIMedit.BrowseState= [ksBrowseMode]
HP TRIM 6 Software Development Kit
Page 148
CannedDatesMode
Returns/Sets which if any canned dates are supported by the control. Ony relevantwhen the controls mode is set to Date or Date Time.
SyntaxTRIMedit.CannedDatesMode= [ksCannedDatesMode]
HP TRIM 6 Software Development Kit
Page 149
CanUndo
Determines if the EditUndo method is able to be used.
SyntaxTRIMedit.CanUndo= [Boolean]
HP TRIM 6 Software Development Kit
Page 150
CaptionWindow
A Windows Handle (HWnd) to a static control. The text of the static control will beused as the caption of the messagebox for any message concerning the TRIMeditControl.
SyntaxTRIMedit.CaptionWindow= [hWnd]
HP TRIM 6 Software Development Kit
Page 151
ConfirmOverwrite
Returns/Sets whether the control will prompt the user when overwriting an existingfile. Only relevant when the control's SelectMode is set to Output File.
SyntaxTRIMedit.ConfirmOverwrite= [Boolean]
HP TRIM 6 Software Development Kit
Page 152
CurSel
Returns/Sets the index of the item selected on the dropdown list,
SyntaxTRIMedit.CurSel= [Long ]
HP TRIM 6 Software Development Kit
Page 153
CursorPosition
Returns/Sets the current position of the cursor in the text area of the control.
SyntaxTRIMedit.CursorPosition= [Long]
HP TRIM 6 Software Development Kit
Page 154
DateTime
Returns/Sets the DateTime value of the control. Only relevant when the control is ineither Date or Date and Time SelectMode.
SyntaxTRIMedit.DateTime= [TRIMdateTime]
HP TRIM 6 Software Development Kit
Page 155
Enabled
Returns/sets a value that determines whether an object can respond to user-generated events.
SyntaxTRIMedit.Enabled= [Boolean]
HP TRIM 6 Software Development Kit
Page 156
ExtraText
Returns/sets any extra text for use in tool tips (for example, if a TRIM record numberis displayed in the text area of the control, the extratext property could be set toequal the title of the record. This would cause it to be displayed if the user hovedthe mouse over the control).
SyntaxTRIMedit.ExtraText = [String]
HP TRIM 6 Software Development Kit
Page 157
ExtraTextInList
Returns/Sets a value that determines if any extra text is displayed as a tooltip on anitem in the dropdown list.
SyntaxTRIMedit.ExtraTextInList = [Boolean]
HP TRIM 6 Software Development Kit
Page 158
FileFilter
Returns/Sets a value that determines which file types to filter for and how to displaythe file type. This property is only used when SelectMode is set to InputFile orOutputFile.
SyntaxTRIMedit.FileFilter = [String ]
Remarks
The expected format of the FileFilter string:
"Description of fileType (A) (B)|*.extensionA;*.extensionB|Description of file Type(C) (D)|*.extensionC; *.extensionD|"
For a single file type:
"Description of the fileType|*.extension|"
Example: "Text Files (*.txt)|*.txt|"
Will add the line "Text Files (*.txt)" to the Files of Type area on the "File OpenConrol" and the "Save As Control" and filter the file list area so that only files withthe extension .txt will be displayed.
For multiple file type support using the one line:
"Description of the fileTypes|*.extension;*.extension|" Note the semicolonbetween the extensions.
Example: "Documents (*.txt) (*.doc) (*.html)|*.txt;*.doc;*.html|"
Will add the line "Documents (*.txt) (*.doc) (*.html)" to the Files of Type area onthe "File Open Control" and the "Save As Control" and filter the file list area so thatonly files with the extensions *.txt; *.doc or *.html will be displayed.
For multiple file type support using the more than one line:
"Description of the fileTypes|*.extension;*.extension|Description2 of thefileTypes|*.extension2;*.extension2 |"" Note the pipe that seperates thedescription from the file extensions is also used to separate a new line for use in theFiles of Type dropdown list on the relevant controls.
Example: "Documents (*.txt) (*.doc)|*.txt;*.doc|Web Documents (*.html)(*.htm)|*.html;*.htm|"
Will add two lines to the Files of Type dropdown list
1. "Documents (*.txt) (*.doc)" - when this line is selected the file list area isfiltered so that only files with the extensions *.txt or *.doc will be displayed.
2. "Web Documents (*.html) (*.htm)" - when this line is selected the file list areais filtered so that only files with the extensions *.html or *.htm will bedisplayed.
The line "All Files (*.*)" is always on the dropdown list so it does not need to beadded, it is the default value for the Files of Type field if the FileFilter property is leftblank. If there is a value in the FileFilter property it will be selected by default, ifthere is more than one line the first line is selected by default. In the above example"Documents (*.txt) (*.doc)" will be the default.
HP TRIM 6 Software Development Kit
Page 159
Font
Returns/Sets the font used in the text area of the control.
SyntaxTRIMedit.Font = [stdole.IFontDisp]
HP TRIM 6 Software Development Kit
Page 160
ForceSpellCheck
Returns/Sets the value that determines if a spelling check must be performed on thestring in the text area of the control. The spelling check does not happenautomaticaly, it is a flag for the programmer to use to indicate if the SpellCheckmethod needs to be run befor the information is saved or the form is closed etc.
SyntaxTRIMedit.ForceSpellCheck = [Boolean]
Remarks
If the program requires that the user run the Spelling Check on the text in theTRIMedit control the theory would be to set the flag to true at design time or onload. If the user clicks the spell check button the program could catch theBrowseSelected event and set the ForceSpellCheck property to false. Likewise if theuser changes the contents of the TRIMedit control the program could catch theChange event and set ForceSpellCheck back to true. This property could then bechecked on the programs save or close function and the SpellCheck method called ifrequired.
HP TRIM 6 Software Development Kit
Page 161
HistoryCount (Read Only)
Returns/Sets the count of the number of history items.
SyntaxTRIMedit.HistoryCount = [Long]
HP TRIM 6 Software Development Kit
Page 162
HistoryKey
Returns/Sets the registry key that the TRIMedit control will store and retrieve itshistory items from.
SyntaxTRIMedit.HistoryKey = [String ]
Remarks
The Historykey is always prefixed with "HKEY_CURRENT_USER\". This means thatyou should NOT include "HKEY_CURRENT_USER\" in the HistoryKey you assign.
History items are loaded and saved to this registry key using the methodsLoadHistory and SaveHistory.
Example:
If you want the history items stored in the following registry key:HKEY_CURRENT_USER\Software\My Cool Context SDK Appliction\TRIMedit History
Then you would set the HistoryKey property to "Software\My Cool Context SDK
Appliction\TRIMedit History".
HP TRIM 6 Software Development Kit
Page 163
HistoryLimit
Returns/Sets the number of items that can be held in history. When this limit isreached and an item is added to the history, the oldest history item will be dropped.
SyntaxTRIMedit.HistoryLimit = [Long]
HP TRIM 6 Software Development Kit
Page 164
HistoryVisibleRows
Returns/Sets the number of history rows that are displayed on the dropdown list. Toget the total number of items in the dropdown list you would have to add the valueof this property to the value of the ItemsCount property.
SyntaxTRIMedit.HistoryVisibleRows = [Long ]
HP TRIM 6 Software Development Kit
Page 165
HistoryWhenLocked
Returns/Sets a value that determines if a user can select an item on the dropdownlist even if the control is in a locked state.
SyntaxTRIMedit.HistoryWhenLocked= [Boolean]
HP TRIM 6 Software Development Kit
Page 166
ItemCount (Read Only)
Returns the number of non-history items in the dropdown list. To get the totalnumber of items in the dropdown list you would have to add the value of thisproperty to the value of the HistoryVisibleRows property.
SyntaxTRIMedit.ItemCount = [Long]
HP TRIM 6 Software Development Kit
Page 167
Locked
Returns/Sets the locked state of the control. When the control is locked a usercannot enter a value directly into the text area of the control. It may still be possibleto get a value into the text area of the control via the history drop down of the kwickselect button depending on the values of the HistoryWhenLocked and BrowseStateproperties.
SyntaxTRIMedit.Locked = [Boolean]
HP TRIM 6 Software Development Kit
Page 168
MaxLength
Returns/Sets the maximum characters that the user is allowed to enter in the textarea of the control.
SyntaxTRIMedit.MaxLength= [Long ]
HP TRIM 6 Software Development Kit
Page 169
Modified
Returns/Sets a value that determines if the value in the text area of the control haschanged. This property is set to true by the control when a user changes the valuein the text area of the control. It is up to the programmer to set this value back toFalse where appropriate.
SyntaxTRIMedit.Modified= [Boolean]
Remarks
This feature can be used to determine if a save is required when creating your ownrecord entry forms (for example, the values from a record saved in a TRIM Databasecan be displayed in TRIMedit controls on a form or dialog and displayed to a user).When the form or dialog is closed a quick iteration through the Modified property onthe TRIMedit controls can determine if the record needs to be updated and saved.
HP TRIM 6 Software Development Kit
Page 170
MultiLine
Returns/Sets a value that determines if text in the text area of the control can spanmore that a single line. If the text in the text area of the control does not fit in thewidth of a control that has MultiLine set to true, the text will wrap automatically.
SyntaxTRIMedit.MultiLine= [Boolean]
HP TRIM 6 Software Development Kit
Page 171
Name (ReadOnly)
Returns the name used in code to identify this control. The name property can onlybe set at design time.
SyntaxTRIMedit.Name= [String ]
HP TRIM 6 Software Development Kit
Page 172
Number
Returns/Sets a value that determines if all text is allowed in the text area of thecontrol or if the text is limited to numbers only. A control with this property set totrue will not allow non-digit characters to be entered in the text area.
SyntaxTRIMedit.Number= [Boolean]
HP TRIM 6 Software Development Kit
Page 173
PassWord
Returns/Sets a value that determines if text entered in the text area of the control ismasked using the asterisk character.
SyntaxTRIMedit.PassWord= [Boolean]
HP TRIM 6 Software Development Kit
Page 174
ScrollBars
Returns/Sets a value that determines which if any, scroll bars are displayed on thecontrol.
SyntaxTRIMedit.ScrollBars= [ksScrollMode]
HP TRIM 6 Software Development Kit
Page 175
SelectMode
The key property of the control, returns/sets a value that determines what mode thecontrol is in. This in tern determines what the control look like, and its defaultbehavour as well as the relevants of other properties.
SyntaxTRIMedit.SelectMode= [ksSelectMode]
Remarks
See the first table in the TRIMedit section of this help file for a brief overview of thedifferent modes available to this control.
HP TRIM 6 Software Development Kit
Page 176
SelectOnFocus
Returns/Sets a value that determines if the text in the text area of the control getsselected when the control gets focus. If you want the contents of the control to beselected when a user tabs to it, you would set this value to true.
SyntaxTRIMedit.SelectOnFocus= [Boolean]
HP TRIM 6 Software Development Kit
Page 177
TabIndex
Returns/sets the tab order of an object within its parent form.
SyntaxTRIMedit.TabIndex= [Integer]
HP TRIM 6 Software Development Kit
Page 178
TabStop
Returns/sets a value indicating whether a user can use the TAB key to give the focusto this control.
SyntaxTRIMedit.TabStop= [Boolean]
HP TRIM 6 Software Development Kit
Page 179
Tag
Returns/Sets a value that is at the programmers descretion. The primary function ofthe tag property is to store any extra data needed for your program.
SyntaxTRIMedit.Tag= [String]
HP TRIM 6 Software Development Kit
Page 180
Text
Returns/Sets the value displayed in the text area of the control.
SyntaxTRIMedit.Text = [String]
Remarks
If the control is set to Date and Time mode the Date and Time areas of the controlledare joined using a pipe character "|" as a separator (for example, to put the enterthe value "24/01/2002" in the date area and "10:30:00 AM" in the time area thestring passed to the text property would be "24/01/2002|10:30:00 AM").
HP TRIM 6 Software Development Kit
Page 181
ToolTips
Returns/Sets a value that determines if extra text will be displayed for this control asa tooltip.
SyntaxTRIMedit.ToolTips = [Boolean]
HP TRIM 6 Software Development Kit
Page 182
Uri
Returns/Sets a value that is the unique record identifier for the object or recordbeing displayed in the TRIMedit control. It is basically a property like Tag that theprogrammer can use where they think appropriate.
SyntaxTRIMedit.Uri = [Variant]
Remarks
Generally when working with TRIM you will be working with TRIM Record objects orTRIM Location objects. All of these objects are identifiable to TRIM by their Uriproperty.
If for example you have a TRIMedit control in Browse mode that does a lookup for aTRIM location when the Kwick select button is pressed. The user wants to select"Orsen Carte" but there are two in this Database, they can tell from other locationinformation such as address which "Orsen Carte" they want so they select it.
The location name "Orsen Carte" is displayed in the text area of the control but youthe programmer need to keep a reference to the locations Uri in order for you toknow which "Orsen Carte" in the Database to update or attach as a contact to arecord etc.
The controls Uri property could be set to equal the Uri property of the location. Thereference to the TRIM location object could then be destroyed and recreated at anystage using the TRIMSDK.Database.GetLocation method that accepts a Uri andreturns a TRIM location.
HP TRIM 6 Software Development Kit
Page 183
Validated
Returns/Sets a value that determines the validation state of the control.
SyntaxTRIMedit.Validated= [ksEditValidMode]
HP TRIM 6 Software Development Kit
Page 184
WantReturn
If true, allows carriage returns to be inserted upon pressing ENTER in a multilineTRIMEdit Box.
If false, when the user presses ENTER, the dialog's default button will be clicked.
SyntaxTRIMedit.WantReturn= [Boolean]
HP TRIM 6 Software Development Kit
Page 185
Methods
Name Description
AddHistory Adds an item to the history list
AddHistoryAt Adds an item to the history list at a specified index
AddHistoryAtExAdds an item to the history list including Uri and Exra textat a specified index
AddHistoryEx Adds an item to the history list including Uri and Exra text
AddItem Adds an item to the dropdown list
AddItemAt Adds an item to the dropdown list at a specified index
AddItemAtExAdds an item to the dropdown list including Uri and Exratext at a specified index
AddItemExAdds an item to the dropdown list including Uri and Exratext
EditCopy Copies the selected text to the clipboard
EditCutCopies the selected text value to the clipboard and sets theselected text to a null string
EditDelete Sets the text property to a null string
EditPaste Copies the value in the clipboard to the text property
EditUndo Undoes the last command performed in the text area
FindInListReturns the index of the dropdown list item that containsthe specified text
FindUriInListReturns the index of the dropdown list item that has thespecified Uri
GetListAt Returns the text at the specified list index
GetSel Returns the start and end positions of the selected text
GetUriAtReturns the Uri of the dropdown list item that has thespecified index
LoadHistoryLoads any history items in the registry to the dropdown listof the control
PressBrowseWill do the same as if the user had pressed the kwikselectthemselves
RemoveHistory Removes a history item at the specified index
HP TRIM 6 Software Development Kit
Page 186
RemoveItem Removes a dropdown list item at the specified index
ReplaceSel Replaces any the selected text with a specified value
ResetHistoryClears the Histoy collection, removing all history items fromthe registry
ResetItemsClears any items from the dropdown list that are not historyitems
SaveHistory Saves the history items to the registry
SetIcons Internal use only
SetSelSelects text in the control based on the nominated start andend positions
SetupContentsSets up the contents of the control including text, extra textand Uri plus, the valid and modified states
SpellCheck Perform a spell check on the text in the control
VerifyInternal verification of the controls contents and firing ofthe verify method
HP TRIM 6 Software Development Kit
Page 187
AddHistory
Adds the nominated text as a history item for the control.
SyntaxTRIMedit.AddHistory (Text As String)
Parameters
Name Type Default Description
Text String The string to be added as a history item
HP TRIM 6 Software Development Kit
Page 188
AddHistoryAt
Adds the nominated text as a history item for the control at the specified index.
SyntaxTRIMedit.AddHistoryAt (Text As String, index As Long)
Parameters
Name Type Default Description
Text String The string to be added as a history item
Index Long The index at which to add the historyitem
HP TRIM 6 Software Development Kit
Page 189
AddHistoryAtEx
Adds the nominated text as a history item for the control at the specified index alongwith a unique identifier and any extra text.
SyntaxTRIMedit.AddHistoryAtEx (Text As String, index As Long, Uri, ExtraText As String)
Parameters
Name Type Default Description
Text String The string to be added as a history item
Index Long The index at which to add the history item
Uri Variant The unique record identifier of the object thishistory item represents (for example, TRIM RecordUri)
ExtraText String Any extra text you want displayed like a tool tip, ifthe user has the mouse paused over this item (forexample, the TRIM Record Title)
HP TRIM 6 Software Development Kit
Page 190
AddHistoryEx
Adds the nominated text as a history item for the control along with a uniqueidentifier and any extra text. Recommended when dealing with TRIM objects in thecontrol. The item gets added to the top of the history list.
SyntaxTRIMedit.AddHistoryEx (Text As String, Uri, ExtraText As String)
Parameters
Name Type Default Description
Text String The string to be added as a history item
Uri Variant The unique record identifier of the object thishistory item represents (for example, TRIM RecordUri)
ExtraText String Any extra text you want displayed like a tool tip, ifthe user has the mouse paused over this item (forexample, the TRIM Record Title)
HP TRIM 6 Software Development Kit
Page 191
AddItem
Adds the nominated text as an item to the dropdown list for the control. UsingAddItem will not affect the history items (for example, you would use it to adddefault items to the dropdown list that will be displayed regardless of the history).
SyntaxTRIMedit.AddItem (Text As String)
Parameters
Name Type Default Description
Text String The string to be added as an item to thedropdown list
HP TRIM 6 Software Development Kit
Page 192
AddItemAt
Adds the nominated text as an item to the dropdown list for the control at thespecified index. Using AddItemAt will not affect the history items (for example, youwould use it to add default items to the dropdown list that will be displayedregardless of the history).
SyntaxTRIMedit.AddItemAt (Text As String, index As Long)
Parameters
Name Type Default Description
Text String The string to be added as an item to thedropdown list
Index Long The index at which to add the item
HP TRIM 6 Software Development Kit
Page 193
AddItemAtEx
Adds the nominated text as an item to the dropdown list for the control at thespecified index along with a unique identifier and any extra text. Using AddItemAtExwill not affect the history items (for example, you would use it to add default itemsto the dropdown list that will be displayed regardless of the history).
SyntaxTRIMedit.AddItemAtEx (Text As String, index As Long, Uri, ExtraText As String)
Parameters
Name Type Default Description
Filename String The path and file name of the file to be viewed
Index Long The index at which to add the item
Uri Variant The unique record identifier of the object thisdropdown item represents (for example, TRIMRecord Uri)
ExtraText String Any extra text you want displayed like a tool tip,if the user has the mouse paused over this item(for example, the TRIM Record Title)
HP TRIM 6 Software Development Kit
Page 194
AddItemEx
Adds the nominated text as an item to the dropdown list for the control along with aunique identifier and any extra text. Using AddItemEx will not affect the historyitems (for example, you would use it to add default items to the dropdown list thatwill be displayed regardless of the history).
Syntax[Boolean] =TRIMedit.AddItemEx (Text As String, Uri, ExtraText As String)
Parameters
Name Type Default Description
Filename String The path and file name of the file to be viewed
Uri Variant The unique record identifier of the object thisdropdown item represents (for example, TRIMRecord Uri)
ExtraText String Any extra text you want displayed like a tool tip, ifthe user has the mouse paused over this item (forexample, the TRIM Record Title)
HP TRIM 6 Software Development Kit
Page 195
EditCopy
Copy the value of any selected text to the clipboard.
SyntaxTRIMedit.EditCopy ()
HP TRIM 6 Software Development Kit
Page 196
EditCut
Copies the value of the selected text to the clipboard and sets the value of theselected text to a null string.
SyntaxTRIMedit.EditCut ()
HP TRIM 6 Software Development Kit
Page 197
EditDelete
Sets the value of the selected text to a null string.
SyntaxTRIMedit.EditDelete ()
HP TRIM 6 Software Development Kit
Page 198
EditPaste
Sets the value of the selected text to a the string held in the clipboard, updating thetext area of the control.
SyntaxTRIMedit.EditPaste ()
HP TRIM 6 Software Development Kit
Page 199
EditUndo
Undoes the last command performed in the text area. Depends on the CanUndoproperty being set to True.
SyntaxTRIMedit.EditUndo ()
HP TRIM 6 Software Development Kit
Page 200
FindInList
Finds the nominated text in the dropdown list. It must be an exact match of thestring in the dropdown list. It returns the index of the list item where the fist findoccurs. You might use this to ensure you did not add the same value to the list morethan once.
Syntax[Long] =TRIMedit.FindInList (Text As String)
Parameters
Name Type Default Description
Text String The string to find in the dropdown list
Return Value
Type Description
Long Returns index of the item in the list
HP TRIM 6 Software Development Kit
Page 201
FindUriInList
Recommended when using TRIM objects. Finds the first occurance of the nominateduri and returns the index of the list item. The issue with some TRIM objects (forexample, locations is that you can have more than one with the same name). To seeif a location already exists on the list you can use the FindUriInList method.
Syntax[Long] =TRIMedit.FindUriInList (Uri As Variant)
Parameters
Name Type Default Description
Uri Variant The Uri to look for in the list items
Return Value
Type Description
Long Returns index of the item in the list
HP TRIM 6 Software Development Kit
Page 202
GetListAt
Returns the value in the dropdown list at the specified index.
Syntax[String] =TRIMedit.GetListAt (index as Long)
Parameters
Name Type Default Description
index Long Index of the list item you want returned
Return Value
Type Description
String Value of the text in the dropdown list
HP TRIM 6 Software Development Kit
Page 203
GetSel
Returns the start and end positions of the selection. You need to pass in twovariables of the correct type to use this method. The method will set the passed invariables to the position of the start and end characters in the selection. If nothingis selected both values will return 0.
SyntaxTRIMedit.GetSel (startChar As Long, endChar As Long)
Parameters
Name Type Default Description
StartChar Long – Return Value Number that specifies the start ofthe selection in the string
EndChar Long – Return Value Number that specifies the end ofthe selection in the string
HP TRIM 6 Software Development Kit
Page 204
GetUriAt
Returns the Uri of the nominated dropdown list item.
Syntax
[Variant] =TRIMedit.GetUriAt (index As Long)
Parameters
Name Type Default Description
index Long The index of the list item where you wantthe Uri
Return Value
Type Description
Variant Uri of the specified row in the list
HP TRIM 6 Software Development Kit
Page 205
LoadHistory
Loads the history items stored in the registry for this control and adds them to thedropdown list. It relies on the HistoryKey property having a valid value and that theSaveHistory method has been called when the control has had some history items.
SyntaxTRIMedit.LoadHistory ()
HP TRIM 6 Software Development Kit
Page 206
PressBrowse
This will do the same as if the user had pressed the kwikselect themselves.
! Note: Nothing happens if the kwikselect is disabled.
SyntaxTRIMedit.PressBrowse ()
HP TRIM 6 Software Development Kit
Page 207
RemoveHistory
Removes the history item at the specified index.
Syntax[Boolean] = TRIMedit.RemoveHistory (index As Long)
Parameters
Name Type Default Description
Index Long Index of the history item to remove
Return Value
Type Description
Boolean Returns true on success
HP TRIM 6 Software Development Kit
Page 208
RemoveItem
Removes the specified item from the dropdown list.
Syntax[Boolean] =TRIMedit.RemoveItem (index As Long)
Parameters
Name Type Default Description
index Long Index of the dropdown item to remove
Return Value
Type Description
Boolean Returns true on success
HP TRIM 6 Software Development Kit
Page 209
ReplaceSel
Replaces the selected text with the text specified and theis command can be set sothat using EditUndo will reverse it.
SyntaxTRIMedit.ReplaceSel (replaceStr As String, CanUndo As Boolean)
Parameters
Name Type Default Description
ReplaceStr String The string that will replace thecurrent selection
CanUndo Boolean Enables the undo of this Action
HP TRIM 6 Software Development Kit
Page 210
ResetHistory
Clears the history for this control. It is the same as doing a RemoveHistory on eachof the history items.
SyntaxTRIMedit.ResetHistory ()
HP TRIM 6 Software Development Kit
Page 211
ResetItems
Clears the dropdown list of any non history items. It is the same as doing aRemoveItem on each of the items in the dropdown list.
SyntaxTRIMedit.ResetItems ()
HP TRIM 6 Software Development Kit
Page 212
SaveHistory
Saves the control's current history items to the registry at the key specified in theHistoryKey property.
SyntaxTRIMedit.SaveHistory ()
HP TRIM 6 Software Development Kit
Page 213
SetIcons
Internal use only.
Syntax[Boolean] =TRIMedit.SetIcons (smallIcon, bigIcon)
Parameters
Name Type Default Description
smallIcon For internal use only
bigIcon For internal use only
Return Value
Type Description
Boolean For internal use only
HP TRIM 6 Software Development Kit
Page 214
SetSel
Selects text using the start and end positions specified.
Syntax[Boolean] =TRIMedit.SetSel (startChar As Long, endChar As Long)
Parameters
Name Type Default Description
startChar Long Start selection position
endChar Long End Selection Position
HP TRIM 6 Software Development Kit
Page 215
SetupContents
Sets up the contents of the TRIMedit control to save using a number of differentproperties such as Text and Uri. It also has the advantage of being able to set thevalid mode, which you can use to bypass any validation (If you are loading theTRIMedit control with a value that you know is valid you can set the control to a validstate.
SyntaxTRIMedit.SetupContents (Text As String, ExtraText As String, Uri, Validated AsksEditValidMode, Modified As Boolean)
Parameters
Name Type Default Description
Text String Sets the value of the Textproperty
ExtraText String Sets the value of the ExtraTextproperty
Uri Variant Sets the value of the Uriproperty
Validated ksEditValidMode Sets the value of the Validatedproperty
Modified Boolean Sets the value of the Modifiedproperty
HP TRIM 6 Software Development Kit
Page 216
SpellCheck
Runs the TRIM spelling checker against the contents of the text area.
Syntax
TRIMedit.SpellCheck ()
HP TRIM 6 Software Development Kit
Page 217
Verify
Does any verification it can internal to the control such as checking that a date isvalid when in date or datetime mode. It will then fire the controls Verify event.
Syntax[Boolean] =TRIMedit.Verify (displayError As Boolean, forceVerify As Boolean)
Parameters
Name Type Default Description
displayError Boolean If an error occurs during this method thisparameter indicates if they are to bedisplayed
forceVerify Boolean ***UNDER CONSTRUCTION***
Return Value
Type Description
Boolean Returns true on success
HP TRIM 6 Software Development Kit
Page 218
Events
Name Description
Browse Occurs when the Kwick Select button is clicked
BrowseSelectedOccurs when control is returned to the the TRIMedit controlfrom a constituant control
Change Occurs when the contents of the text area is changed
HistoryDelAllowedOccurs if the controls Delete key (Del on some keyboards) ispressed while the dropdown list is dowb and a an itemselected
HistoryDelDoneOccurs if the HistoryDelAllowed event has completed with aresult of deleting the list item
HistorySelected Occurs when a history item is selected from the dropdown list
IdleTimeoutOccurs when user interaction on the control has not occurredfor a short period
LoadHistoryOccurs when the History items for the control are loaded fromthe registry
SaveHistoryOccurs when the the History items for the control are saved tothe registry
SelChangeOccurs when the user selects a different item from thedropdown list
ValidChanged Occurs when the value of the Validated property is changed
Verify Occurs when the Verify method is called
HP TRIM 6 Software Development Kit
Page 219
Browse
Occurs if the controls SelectMode property is set to either ksBrowse or ksFormat andthe kwick select button is clicked.
SyntaxTRIMedit_Browse (reserved As Boolean)
Parameters
Name Type Default Description
Reserved Boolean Reserved for future use
HP TRIM 6 Software Development Kit
Page 220
BrowseSelected
Occurs when control is returned to the TRIMedit control from a constituent control.This event might be used to do extra validation on the information returned by aconstituent control (for example, if the controls SelectMode property is set to ksDate,the date the user has selected might be tested to ensure that it falls within aparticular range required by the application).
SyntaxTRIMedit_BrowseSelected ()
HP TRIM 6 Software Development Kit
Page 221
Change
Similar to the Change event on a Visual Basic Textbox, the event occurs when thecontents of the text area is changed.
SyntaxTRIMedit_Change ()
HP TRIM 6 Software Development Kit
Page 222
HistoryDelAllowed
Occurs if the controls Delete key (Del on some keyboards) is pressed while thedropdown list is down with a user highlighting one of the items on the list. It doesnot matter if the item is a history item or just an item added to the list. This event isused to allow users to remove items from the dropdown list. The removal of the listitem is handeled at the end of the event if you set the allowed parameter to true. Ifthe allowed parameter is set to true and the confirm parameter is also true at theend of the event then a confermation dialog will be displayed and the item deleted orremoved only is the user agrees. If the item is a history item that has been saved,the history item will be cleaned up much like using the RemoveHistory method.
SyntaxTRIMedit_HistoryDelAllowed (index As Long, allowed As Boolean, confirm As Boolean)
Parameters
Name Type Default Description
Index Long Index of the particular history item
Allowed Boolean False Determines if the history item is to be deletedat the end of this event
Confirm Boolean True Determines if the user should be prompted toconfirm the deletion of the history item
HP TRIM 6 Software Development Kit
Page 223
HistoryDelDone
Occurs if the controls HistoryDelAllowed event has finished with a result where theitem has been deleted or removed from the list. This event can be used ifinformation regarding the item in the drop down list is stored in a location other thanthe controls History Key and further cleanup is required by your application.
SyntaxTRIMedit_HistoryDelDone (index As Long, Uri, Text As String)
Parameters
Name Type Default Description
Index Long The list index the item used to have before itwas deleted
Uri Variant 0 The Uri of the list item that was removed. If noUri was set it will have a value of 0
Text String The text that was displayed in the list item thathas been removed
HP TRIM 6 Software Development Kit
Page 224
HistorySelected
Occurs if an item on the dropdown list has been selected by the user.
SyntaxTRIMedit_HistorySelected ()
HP TRIM 6 Software Development Kit
Page 225
IdleTimeout
***UNDER CONSTRUCTION***
Occurs each time the user has had no interaction with the control for a time period.This event can be used to do some extra validation on the contents of the control.
SyntaxTRIMedit_IdleTimeout ()
HP TRIM 6 Software Development Kit
Page 226
LoadHistory
Occurs when the history items for the control are loaded from the registry. Thisevent can be used to add other default items to the controls dropdown list.
SyntaxTRIMedit_LoadHistory ()
HP TRIM 6 Software Development Kit
Page 227
SaveHistory
Occurs when the history items are saved to the registry. This event can be used tosave other non-history items in the controls dropdown list.
SyntaxTRIMedit_SaveHistory ()
HP TRIM 6 Software Development Kit
Page 228
SelChange
Occurs if a different item on the dropdownlist has been selected.
SyntaxTRIMedit_SelChange ()
HP TRIM 6 Software Development Kit
Page 229
ValidChanged
Occurs if the value of the controls Validated property has changed.
SyntaxTRIMedit_ValidChanged ()
HP TRIM 6 Software Development Kit
Page 230
Verify
Occurs if the controls Verify method has been called. This event gives you theopportunity to do any extra validation (on top of the validation native to the controland its settings) and determine the new valid state of the control, the value of thecontrols Validated property.
SyntaxTRIMedit_Verify (displayError As Boolean, newValidState As ksEditValidMode)
Parameters
Name Type Default Description
DisplayError Boolean Determines if a dialog is to bedisplayed with any error information
NewValidState ksEditValidMode The valid state of the control
HP TRIM 6 Software Development Kit
Page 231
Tree Box - TRIMtreeBox
The TRIMtreeBox control is used to display lists of items. In HP TRIM it is used todisplay lists of records, locations and many other TRIM objects.
TRIMtreeBox listing records in the HP TRIM Demodb Database.
HP TRIM 6 Software Development Kit
Page 232
Sample Code
TRIMtreeBox – list TRIM records example (Visual Basic)
TRIMtreeBox – list TRIM records example (C#)
TRIMtreeBox – Bouncing list example (Visual Basic)
HP TRIM 6 Software Development Kit
Page 233
TRIMtreeBox - List TRIM Records Visual Basic Example
The purpose of this code snippet is to demonstrate how with a minimum of effort alist of TRIM objects can be displayed in a manner consistent with TRIM. A list thatcan handle tree type behaviour along with sorting, tagging and icon display.
To use this code snippet you will need to:
1. Add a TRIMtreeBox control to a Visual Basic form and ensure that the name ofthe TRIMtreeBox control is TRIMtreeBox1
2. Add two Visual Basic CommandButton controls to the form and ensure they arenamed Command1 and Command2
3. Size the Form and TRIMtreeBox Control so that it is wide enough to makesense.Form example:
4. Set the Tagging Mode property of the TRIMtreeBox to Enabled,"TRIMtreeBox1.TaggingMade = tbtmTags".
TRIM objects and the methods, properties and events used in this example;
Objects
TRIMOCXLib.TRIMtreeBox
TRIMSDK.Database
TRIMSDK.PropertyDefs
TRIMSDK.RecordSearch
TRIMSDK.Records
TRIMSDK.Record
Methods
TRIMtreeBox
AddManyColumns
AddManyRows
GetFirstRow
GetNextRow
HP TRIM 6 Software Development Kit
Page 234
Database
NewRecordSearch
MakeRecords
GetRecord
PropertyDefs
SelectTreeColumns
GetTreeInitString
RecordSearch
EditQueryUI
GetRecords
Records
SelectContentsOf
GetTreeString
SelectByUris
DisplayUI
Properties
TRIMtreeBox
Message
AnyTagged
CurrentRow
Records
Count
Record
IsContainer
Events
TRIMtreeBox
AboutToExpand
In the forms code area copy and paste the following code;
Visual Basic ExampleOption Explicit'// Modular level (m_)Private m_TRIMDatabase As TRIMSDK.DatabasePrivate m_PropertyDefs As TRIMSDK.PropertyDefsPrivate Sub Command1_Click()
'// Clicking the Command1 button causes a TRIM search dialog to be displayed. Anyrecords returned by the search are listed in the TRIMtreeBox.
'// Procedural level variables (p_)Dim p_RecordSearch As TRIMSDK.RecordSearchDim p_Records As TRIMSDK.Records
HP TRIM 6 Software Development Kit
Page 235
Dim p_blnClickedOK As BooleanSet m_TRIMDatabase = New TRIMSDK.Database'/// This bit gets some TRIM Records that will be listed in the TRIMtreeBox control.'// Instantiate a new Record Search object.Set p_RecordSearch = m_TRIMDatabase.NewRecordSearch
'// Use the EditQueryUI method of the search object to '//display the TRIM searchdialog. This method returns a boolean that indicates if the user clicked the OK or cancelbutton
p_blnClickedOK = p_RecordSearch.EditQueryUI(Me.hWnd)If p_blnClickedOK = True Then
'// User clicked the OK button so the search is done. Load any recordreturned by the search in to the TRIM Records object
Set p_Records = p_RecordSearch.GetRecordsElse
'/// User clicked the cancel buttonExit Sub
End If
'/// This bit gets just the default TreeColumns for a TRIM Record object into theTRIMtreeBox control
'/// Get the default columns for TRIM Records'// Instantiate the Property Definitions objectSet m_PropertyDefs = New TRIMSDK.PropertyDefs
'/// Use the SelectTreeColumns method to get the default property '/// definitions.'/// To be used as column headers in a TRIMtreeBoxm_PropertyDefs.SelectTreeColumns btyRecord, True
'/// Add the names of the default property definitions as column '/// headers to theTRIMtreeBox
TRIMtreeBox1.AddManyColumns m_PropertyDefs.GetTreeInitString(m_TRIMDatabase,False)
'/// Add the values of the default record properties to the'/// TRIMtreeBox for the records returned by the searchIf p_Records.Count > 0 Then
TRIMtreeBox1.Message = vbNullStringTRIMtreeBox1.AddManyRows p_Records.GetTreeString(m_PropertyDefs)
Else'// If no records were found add an appropriate comment to the Edit boxTRIMtreeBox1.Message = "No Records found."
End IfEnd Sub
Private Sub Command2_Click()'/// Clicking the Command2 button shows how the Tagged rows in a TRIMtreebox can be used
to retrieve the associated objects from TRIM. In this example the records represented by anytagged rows are simply retrieved and displayed but from this you can see how you mightiterate through any tagged times performing the same function. Eg. You might set the assigneelocation on all the tagged records to a location selected by the user, Etc.
'// Procedural level variables (p_)Dim p_TRIMtreeRow As TRIMOCXLib.TRIMtreeRowDim p_Records As TRIMSDK.RecordsDim p_lngUriAr() As LongDim p_intUriCntr As Integer
p_intUriCntr = -1
'// Check to see that there are some tagged rowsIf TRIMtreeBox1.AnyTagged Then
'// Get the first row, indicating that we are referring to tagged rows only.From this point on GetNextRow will return the next tagged row
Set p_TRIMtreeRow = TRIMtreeBox1.GetFirstRow(True, False)'// Loop until we have all the rowsDo While Not p_TRIMtreeRow Is Nothing
p_intUriCntr = p_intUriCntr + 1ReDim Preserve p_lngUriAr(p_intUriCntr)
HP TRIM 6 Software Development Kit
Page 236
'// Put the row uri into our arrayp_lngUriAr(p_intUriCntr) = p_TRIMtreeRow.Uri'// Get the next tagged row...Set p_TRIMtreeRow = TRIMtreeBox1.GetNextRow
Loop
'// Get the tagged records from the Database and display them'// Instantiate a new RecordsSet p_Records = m_TRIMDatabase.MakeRecords'// Fill the Records object using the array of uris retrieved from the
TRIMtreeBox.p_Records.SelectByUris p_lngUriAr'// Display the records in a TRIM Records dialogp_Records.DisplayUI Me.hWnd
End IfEnd Sub
'/// The TRIMtreeBox1_AboutToExpand event occurs when a user clicks the plus box on aTRIMtreeBox RowPrivate Sub TRIMtreeBox1_AboutToExpand(ByVal Row As TRIMOCXLib.TRIMtreeRow)
'// Procedural level variables (p_)Dim p_Record As TRIMSDK.RecordDim p_Records As TRIMSDK.Records
'// If the row has ever been expanded nothin needs to be done...If Row.EverExpanded = False Then
'// Get the record from the Database object based on the uri stored in theTRIMtreeBox.
Set p_Record = m_TRIMDatabase.GetRecord(Row.Uri)'// Check that the record is a containerIf p_Record.IsContainer Then
'// Instantiate a new Records objectSet p_Records = m_TRIMDatabase.MakeRecords'// Fill the Records object with any records that are contained within
the selected recordp_Records.SelectContentsOf p_RecordIf p_Records.Count > 0 Then
'// If there were some contained records then add them to thecurrent row
Row.AddManyRows(p_Records.GetTreeString(m_PropertyDefs)End If
End IfEnd If
End Sub
HP TRIM 6 Software Development Kit
Page 237
TRIMtreeBox - List TRIM Records C# Example
The purpose of this code snippet is to demonstrate how with a minimum of effort alist of TRIM objects can be displayed in a manner consistent with TRIM. A list thatcan handle tree type behaviour along with sorting, tagging and icon display.
To use this code snippet you will need to:
1. Add a TRIMtreeBox control to a C# form and ensure that the name of theTRIMtreeBox control is axTRIMtreeBox1
2. Add two Button controls to the form and ensure they are named Button1 andButton2
3. Size the Form and TRIMtreeBox Control so that it is wide enough to makesense.Form example:
4. Set the Tagging Mode property of the TRIMtreeBox to Enabled,"TRIMtreeBox1.TaggingMade = tbtmTags".
TRIM objects and the methods, properties and events used in this example;
Objects
TRIMOCXLib.TRIMtreeBox
TRIMSDK.Database
TRIMSDK.PropertyDefs
TRIMSDK.RecordSearch
TRIMSDK.Records
TRIMSDK.Record
Methods
TRIMtreeBox
AddManyColumns
AddManyRows
GetFirstRow
GetNextRow
HP TRIM 6 Software Development Kit
Page 238
Database
NewRecordSearch
MakeRecords
GetRecord
PropertyDefs
SelectTreeColumns
GetTreeInitString
RecordSearch
EditQueryUI
GetRecords
Records
SelectContentsOf
GetTreeString
SelectByUris
DisplayUI
Properties
TRIMtreeBox
Message
AnyTagged
CurrentRow
Records
Count
Record
IsContainer
Events
TRIMtreeBox
AboutToExpand
In the forms code area copy and paste the following code;
C# Example// Modular level (m_)private TRIMSDK.Database m_TRIMDatabase = null;private TRIMSDK.PropertyDefs m_PropertyDefs = null;private string [] m_UrisReceived = null;private TRIMSDK.RecordSearch m_RecordSearch = null;
private void button1_Click(object sender, System.EventArgs e){
// Any records returned by the search are listed in the TRIMtreeBoxbool p_blnClickedOK;m_TRIMDatabase = new TRIMSDK.Database();
HP TRIM 6 Software Development Kit
Page 239
// This bit gets some TRIM Records that will be listed in the TRIMtreeBox control
// Instantiate a new Record Search objectm_RecordSearch = m_TRIMDatabase.NewRecordSearch();// Use the EditQueryUI method of the search object to display the TRIM search dialog.
This method returns a boolean that indicates if the user clicked the OK or cancel buttonp_blnClickedOK = m_RecordSearch.EditQueryUI(Handle.ToInt32());if (p_blnClickedOK == false) return; // User clicked cancel.// This bit gets just the default TreeColumns for a TRIM Record object into the
TRIMtreeBox control// Instantiate the Property Definitions objectm_PropertyDefs = new TRIMSDK.PropertyDefs();// Use the SelectTreeColumns method to all property definitions possible for use as tree
columns to be used as column headers in a TRIMtreeBoxm_PropertyDefs.SelectTreeColumns (TRIMSDK.btyBaseObjectTypes.btyRecord, false);// Add the names of the default property definitions as column headers to the
TRIMtreeBoxaxTRIMtreeBox1.AddManyColumns (m_PropertyDefs.GetTreeInitString (m_TRIMDatabase,
false));// Dim the Uris received array to 0m_UrisReceived = new string[0];axTRIMtreeBox1.Message = null;// Set the Full property of the TRIMtreeBox control to False. The control will then
test to see if there is any room for more rows which is obviously true initially because it isempty. This in turn will cause the RoomForRows event to fire starting the process of thebouncing list...
axTRIMtreeBox1.Full = false;}
// The TRIMtreeBox1_AboutToExpand event occurs whrn a user clicks the plus box on a TRIMtreeBoxRowprivate void TRIMtreeBox1_AboutToExpand (TRIMOCXLib.TRIMtreeRowClass Row){
// If the row has ever been expanded nothing needs to be done...if (Row.EverExpanded == false){
// Get the record from the Database object based on the uri stored in theTRIMtreeBox
TRIMSDK.Record p_Record = m_TRIMDatabase.GetRecord(Row.Uri);// Check that the record is a containerif (p_Record.IsContainer){
// Instantiate a new Records objectTRIMSDK.Records p_Records = m_TRIMDatabase.MakeRecords();// Fill the Records object with any records that are contained within the
selected recordp_Records.SelectContentsOf(p_Record);if (p_Records.Count > 0){
// If there were some contained records then add them to thecurrent row...
string defA = "0";bool defB = false;Row.AddManyRows (p_Records.GetTreeString(m_PropertyDefs,false,
-1,out defA,out defB));
}}
}}
private void axTRIMtreeBox1_RoomForRows(object sender,AxTRIMOCXLib.ITRIMtreeBoxEvents_RoomForRowsEvent e){
// The "Count" parameter passed in is the number of rows required to enable a Page Downto function. That is the number of rows required to refil the visable area. If performance isan issue then count can be used in the GetTreeString method as is done in this example.However you can use any number that may be more apporpriate. Eg. '50' will return 50 rows andthis event will not fire until the user has made it to within a display areas worth of rows.
HP TRIM 6 Software Development Kit
Page 240
// Procedural level variables (p_)string p_strUrisReturned;bool p_blnRecordListExhausted;
// Test the first element in the uri array to see if there is a value. If there is addan "and not uris(uri array) clause to the search so we dont get the same records that arealready in the TRIMtreeBox
if (m_UrisReceived.GetLength(0) > 0){
m_RecordSearch.AddUrisClause(m_UrisReceived);m_RecordSearch.Not();m_RecordSearch.And();
}// Use the GetTreeString to Add only a certain number of rows "MaximunRowsToReturn" to
the TRIMtreeBoxstring txt = m_RecordSearch.GetRecords().GetTreeString (m_PropertyDefs,
false,e.count,out p_strUrisReturned,out p_blnRecordListExhausted);
axTRIMtreeBox1.AddManyRows(txt);// Set the Full property true when there are no longer any rows to return. This removes
the "More To Go" Icon from at the right of the horizontal scrollbar and prevents this eventfrom firing.
axTRIMtreeBox1.Full = p_blnRecordListExhausted;// Reset the UriArray to those returned from the GetTreeString methodm_UrisReceived = null;m_UrisReceived = p_strUrisReturned.Split(",".ToCharArray());// If there are no more rows to get and there are none in the TRIMtreeBox then the
search did not return any recordsif (axTRIMtreeBox1.Full && axTRIMtreeBox1.Count == 0){
axTRIMtreeBox1.Message = "No Records Found";}
}
HP TRIM 6 Software Development Kit
Page 241
TRIMtreeBox - Bouncing List Visual Basic Example
The purpose of this code snippet is to demonstrate how to create a bouncing list.That is a TRIMtreeBox control that only loads (gets from the Database) so manyrecords at a time returning to get more records when required. This is to returncontrol to the user as soon as the control has some records to display.
To use this code snippet you will need to:
1. Add a TRIMtreeBox control to a Visual Basic form so that the name of theTRIMtreeBox control is TRIMtreeBox1
2. Add a Visual Basic CommandButton control to the form and ensure it is namedCommand1
3. Set the Scroll Bars property of the TRIMtreeBox to Both,"TRIMtreeBox1.ScrollBars = ksBoth".
4. Size the Form and TRIMtreeBox Control so that it wide enough to make sense.Form example:
TRIM objects and the methods, properties and events used in this example;
Objects
TRIMOCXLib.TRIMtreeBox
TRIMSDK.Database
TRIMSDK.PropertyDefs
TRIMSDK.RecordSearch
TRIMSDK.Records
TRIMSDK.Record
Methods
TRIMtreeBox
AddManyColumns
AddManyRows
Database
NewRecordSearch
HP TRIM 6 Software Development Kit
Page 242
MakeRecords
GetRecord
PropertyDefs
SelectTreeColumns
RecordSearch
ChooseManyUI
SelectContentsOf
GetTreeString
Properties
TRIMtreeBox
Message
Full
Record
IsContainer
Events
TRIMtreeBox
AboutToExpand
RoomForRows
In the forms code area copy and paste the following code;
Option Explicit'// Modular level (m_)
Private m_TRIMDatabase As TRIMSDK.DatabasePrivate m_PropertyDefs As TRIMSDK.PropertyDefsPrivate m_UrisReceived() As StringPrivate m_RecordSearch As TRIMSDK.RecordSearch
Private Sub Command1_Click()'// Clicking the Command1 button causes a TRIM search dialog to be '// displayed. Anyrecords returned by the search are listed in the '// TRIMtreeBox
'// Procedural level variables (p_)Dim p_blnClickedOK As BooleanSet m_TRIMDatabase = New TRIMSDK.Database'/// This bit gets some TRIM Records that will be listed in the TRIMtreeBox control'// Instantiate a new Record Search objectSet m_RecordSearch = m_TRIMDatabase.NewRecordSearch'// Use the EditQueryUI method of the search object to display the TRIM search dialog'// This method returns a boolean that indicates if the user clicked the OK or cancel
buttonp_blnClickedOK = m_RecordSearch.EditQueryUI(Me.hWnd)If p_blnClickedOK = False Then Exit Sub '///User clicked cancel'/// This bit gets just the defult TreeColumns for a TRIM Record object into the
TRIMtreeBox control'/// Get the default columns for TRIM Records'// Instantiate the Property Definitions objectSet m_PropertyDefs = New TRIMSDK.PropertyDefs'/// Use the SelectTreeColumns method to all property definitions possible for use as
tree columns'/// to be used as column headers in a TRIMtreeBoxm_PropertyDefs.SelectTreeColumns btyRecord, False
HP TRIM 6 Software Development Kit
Page 243
'/// Add the names of the default property definitions as column headers to theTRIMtreeBox
TRIMtreeBox1.AddManyColumns m_PropertyDefs.GetTreeInitString(m_TRIMDatabase,False)
'// Dim the Uris received array to 0ReDim m_UrisReceived(0)TRIMtreeBox1.Message = vbNullString'/// Set the Full property of the TRIMtreeBox control to False'/// The control will then test to see if there is any room for more rows'/// which is obvously true initially because it is empty'/// this in turn will cause the RoomForRows event to fire starting the process of the
bouncing list...TRIMtreeBox1.Full = False
End Sub
'/// The TRIMtreeBox1_AboutToExpand event occurs when a user clicks'/// the plus box on a TRIMtreeBox RowPrivate Sub TRIMtreeBox1_AboutToExpand(ByVal Row As TRIMOCXLib.TRIMtreeRow)'// Procedural level variables (p_)
Dim p_Record As TRIMSDK.RecordDim p_Records As TRIMSDK.Records'// If the row has ever been expanded nothin needs to be done...If Row.EverExpanded = False Then
'// Get the record from the Database object based on the uri stored in theTRIMtreeBox
Set p_Record = m_TRIMDatabase.GetRecord(Row.Uri)'// Check that the record is a containerIf p_Record.IsContainer Then
'// Instantiate a new Records objectSet p_Records = m_TRIMDatabase.MakeRecords'// Fill the Records object with any records that are contained within
the selected recordp_Records.SelectContentsOf p_RecordIf p_Records.Count > 0 Then'// If there were some contained records then add them to the current
row...Row.AddManyRows p_Records.GetTreeString(m_PropertyDefs)
End IfEnd If
End IfEnd Sub
Private Sub TRIMtreeBox1_RoomForRows(ByVal Count As Long)'// The "Count" parameter passed in is the number of rows required to enable a Page Down
to function. That is the number of rows required to refil the visable area.If performance is an issue then count can be used in the GetTreeString method as is done inthis example.However you can use any number that may be more apporpriate. Eg. '50' will return 50 rows andthis event will not fire until the user has made it to within a display areas worth of rows.
'// Procedural level variables (p_)Dim p_strUrisReturned As StringDim p_blnRecordListExausted As Boolean'// Test the first element in the uri array to see if there is a value. If there is add
an "and not uris(uri array) clause to the search so we dont get the same records that arealready in the TRIMtreeBox.
If Len(m_UrisReceived(0)) > 0 Thenm_RecordSearch.AddUrisClause (m_UrisReceived)m_RecordSearch.Notm_RecordSearch.And
End If'// Use the GetTreeString to Add only a certine number of rows "MaximunRowsToReturn" to
the TRIMtreeBoxTRIMtreeBox1.AddManyRows m_RecordSearch.GetRecords.GetTreeString(m_PropertyDefs,
False, Count, p_strUrisReturned, p_blnRecordListExausted)'// Set the Full property true when there are no longer any rows to return. This removes
the "More To Go" Icon from at the right of the horizontal scrollbar and prevents this eventfrom firing
TRIMtreeBox1.Full = p_blnRecordListExausted'// Reset the UriArray to those returned from the GetTreeString methodErase m_UrisReceived
HP TRIM 6 Software Development Kit
Page 244
m_UrisReceived = Split(p_strUrisReturned, ",")'// If there are no more rows to get and there are none in the TRIMtreeBox then the
search did not return any recordsIf TRIMtreeBox1.Full And TRIMtreeBox1.Count = 0 Then
TRIMtreeBox1.Message = "No Records Found"End If
End Sub
HP TRIM 6 Software Development Kit
Page 245
Properties
Name Description
AllowExpandAllReturns/Sets a value that determines all rows in thecontrol can be expanded
AllowSortReturns/Sets a value that determines if the contents ofthe control can be sorted
AnyTaggedReturns/Sets a value that indicates if any of the rows inthe control are tagged
ColumnCount Returns/Sets the number of columns in the control
ColumnsLocked Returns/Sets the lock state for the columns in the control
Count Returns/Sets the number of rows in the control
CurrentRow Returns/Sets the current (selected) row in the control
CurSel Returns/Sets the index of the current (selected) row
DbId Internal use Only
Font The font used by the control when displaying text
FullReturns/Sets a value that indicates that all result rowshave been added to the control
HeadingReturns/Sets a value that determines if the header row(column names) are displayed
IdealHeightReturns a number that when used as the height willdisplay all rows if possible
IdealWidthReturns a number that when used as the width willdisplay columns with out hiding any information
Message Returns/Sets a text message for the user
NumberTagged Returns/Sets the number of tagged rows
PrefixPopupReturns/Sets that determines if a Prefix dialog isdisplayed when the user starts typing while this controlhas focus
RegKeyReturns/Sets a registry key value used when saving orloading a column state
RowHeightReturns/Sets the height of the individual rows in thecontrol
ScrollBars Returns/Sets a value that determines which if any scroll
HP TRIM 6 Software Development Kit
Page 246
bars will be displayed
SelectFirstRowReturns/Sets a value that determines if the first row inthe control will be selected
ShowCurSelReturns/Sets a value that determines if the selected rowwill be highlighted
SnapLastColumnSizes the width of the last column to fit the availablespace
TaggingModeReturns/Sets a value that determines if any tagging isallowed in the control
TagNewRowsReturns/Sets a value that determines if any new rows willautomatically be tagged when added to the control
ToolTipsReturns/Sets a value that determines if ToolTips areactive for this control
TopSelReturns/sets a value that is the index of the row that iscurrently displayed at the top of the control
HP TRIM 6 Software Development Kit
Page 247
AllowExpandAll
Returns/Sets a value that determines if rows in the treebox can be expanded in arecursive fashion.
SyntaxTRIMtreeBox.AllowExpandAll = [Boolean]
HP TRIM 6 Software Development Kit
Page 248
AllowSort
Returns/Sets a value that determines if rows in the treebox can be sorted based inthe values in a column.
SyntaxTRIMtreeBox.AllowSort = [Boolean]
HP TRIM 6 Software Development Kit
Page 249
AnyTagged (Read Only)
Returns a value that indicates if any rows in the treebox have been tagged.
Syntax[Boolean] = TRIMtreeBox.AnyTagged
HP TRIM 6 Software Development Kit
Page 250
ColumnCount (Read Only)
Returns a value that indicates the number of columns currently in the treebox.
Syntax[Long] = TRIMtreeBox.ColumnCount
HP TRIM 6 Software Development Kit
Page 251
ColumnsLocked
When ColumnsLocked is TRUE, the columns cannot be resized, repositioned orotherwise altered (although they can still be sorted by). The menu displayed by theRight Mouse Button is also removed.
Syntax[Boolean] = TRIMtreeBox.ColumnsLocked
HP TRIM 6 Software Development Kit
Page 252
Count (Read Only)
Returns a value that indicates the number of rows in the treebox.
Syntax[Long] = TRIMtreeBox.Count
HP TRIM 6 Software Development Kit
Page 253
CurrentRow (Read Only)
Returns the current selected row in the treebox.
Syntax[TRIMtreeRow] = TRIMtreeBox.CurrentRow
HP TRIM 6 Software Development Kit
Page 254
CurSel
Returns the index of the currently selected row or sets the current selected row bythe index.
SyntaxTRIMtreeBox.CurSel = [Long]
HP TRIM 6 Software Development Kit
Page 256
Font
Returns/Sets the font used to display text in the treebox.
SyntaxTRIMtreeBox. Font = [stdole.IFontDisp]
HP TRIM 6 Software Development Kit
Page 257
Full
Returns/Sets a value that indicates if the treebox has loaded all of the availablerows.
SyntaxTRIMtreeBox. Full = [Boolean]
HP TRIM 6 Software Development Kit
Page 258
Heading
Returns/Sets a value that determines if the column heading is used.
SyntaxTRIMtreeBox.ColumnCount = [Boolean]
HP TRIM 6 Software Development Kit
Page 259
IdealHeight (Read Only)
Returns a value that indicates
***UNDER CONSTRUCTION***
Syntax[Long] = TRIMtreeBox.Count
HP TRIM 6 Software Development Kit
Page 260
IdealWidth (Read Only)
Returns a value that if used, as the controls width will display all visible columns inthe treebox.
Syntax[TRIMtreeRow] = TRIMtreeBox.CurrentRow
HP TRIM 6 Software Development Kit
Page 261
Message
Returns/Sets a string that is displayed in the list area of the control. When this valueis a null string the controls rows are displayed. If it contains any text, no rows aredisplayed and the list area becomes like a text box where this message is displayed(for example, if you are using this control to display the results of a search and thesearch returned nothing, you could display an appropriate message to the user bysetting this property).
SyntaxTRIMtreeBox.Message = [String]
HP TRIM 6 Software Development Kit
Page 262
NumberTagged (Read Only)
Returns a value that is the number of tagged rows.
Syntax[Long] = TRIMtreeBox.NumberTagged
HP TRIM 6 Software Development Kit
Page 263
PrefixPopup
Returns/Sets a value that determines if a select by prefix dialog will be displayed ifthe user starts typing while the treebox control has focus. The treebox will thendisplay the list with any rows where the sort column value starts with the enteredprefix. It is used as a quick way to jump to the desired row in a large list.
SyntaxTRIMtreeBox.PrefixPopup = [Boolean]
The Prefix Popup Dialog:
HP TRIM 6 Software Development Kit
Page 264
RegKey
Returns/Sets the registry key value where the column state of the treebox will besaved.
SyntaxTRIMtreeBox. RegKey = [String]
Remarks
The string, "HKEY_CURRENT_USER\" is always used to prefix the value of thisproperty. To save the the column state at the following registry key:HKEY_CURRENT_USER\Software\My Cool Context SDK Appliction\TRIMtreeBox History
The value of this property would be set to:Software\My Cool Context SDK Appliction\TRIMtreeBox History
HP TRIM 6 Software Development Kit
Page 265
RowHeight (Read Only)
Returns the height of a single row to allow for sizing of the control so that no rowswill be cut off.
Syntax[Long] = TRIMtreeBox.RowHeight
HP TRIM 6 Software Development Kit
Page 266
ScrollBars
Returns/Sets a value that determines if and which ScrollBars will be used by thetreebox control.
SyntaxTRIMtreeBox.ScrollBars= [ksScrollMode]
HP TRIM 6 Software Development Kit
Page 267
SelectFirstRow
Returns/Sets a value that determines if the first row in the treebox will be selectedby default.
SyntaxTRIMtreeBox.SelectFirstRow= [Boolean]
HP TRIM 6 Software Development Kit
Page 268
ShowCurSel
Returns/Sets a value that determines if the selected treebox row is highlighted.Useful in situations where the user selecting a row does not make sense to yourapplication. If set to False, it can make it appear to the user that clicking on a rowdoes nothing.
SyntaxTRIMtreeBox.ShowCurSel= [Boolean]
HP TRIM 6 Software Development Kit
Page 269
SnapLastColumn
Returns/Sets a value that indicates if the last column should be sized to end at theend of the treebox. Useful when there is only one column in the treebox control,when set to True the column width will be that of the treebox control making itappear neat.
SyntaxTRIMtreeBox.SnapLastColumn = [Boolean]
HP TRIM 6 Software Development Kit
Page 270
TaggingMode
Returns/Sets a value that determines if tagging is allowed.
SyntaxTRIMtreeBox.TaggingMode = [tbTagMode]
HP TRIM 6 Software Development Kit
Page 271
TagNewRows
Returns/Sets a value that determines if rows added to the treebox control will betagged automatically. Generaly not used as it is set to true when the TagAll methodis called.
SyntaxTRIMtreeBox.TagNewRows = [Boolean]
HP TRIM 6 Software Development Kit
Page 272
ToolTips
Returns/Sets a value that determines if tooltips will be active or not.
SyntaxTRIMtreeBox.ToolTips = [Boolean]
HP TRIM 6 Software Development Kit
Page 273
TopSel
Returns/Sets the index of the top most visable row in the treebox. This will usuallyreturn "0" the first row in the list unless the user has scrolled down in which case youget the index of the first row that is visable. Use this property and the CurSelproperty in the TopSelChanged event to set the current row to be the top mostvisable row.
Syntax[Long] = TRIMtreeBox.TopSel
Sample:Private Sub TRIMtreeBox_TopSelChanged()TRIMtreeBox.CurSel = TRIMtreeBox.TopSelEnd Sub
HP TRIM 6 Software Development Kit
Page 274
Methods
Name Description
AddColumn Adds a column to the control
AddColumnEx Adds a column to the control
AddManyColumns Adds many columns to the control
AddManyRows Adds many rows to the control
AddRow Adds a row to the control
AddRowEx Adds a row to the control
ClearColumns Clears the control
ClearList Clears the rows in the control
CollapseRow Causes an expanded row to collapse
CustomizeColumnsDisplays a dialog to enable some modification on thecolumns
DeleteColumn Removes a column from the control
DeleteRow Removes a row from the control
ExpandRow Display child rows
FindRow Find a row based on entered criteria
FindRowEx Find a row based on entered criteria
FindRowEx2 Find a row based on entered criteria
GetFirstColumn Get the first column on the control
GetFirstRow Get the first row on the control
GetNextColumn Get the next column on the control
GetNextRow Get the next row on the control
GetRow Get a row based on its index
GetRowRectDetermine the bounding rectangle on the screen in pixelsfor a particular row index in a tree box
InsertRow Add a row to the control at a particular index
InsertRowEx Add a row to the control at a particular index
LoadColumnState Restore the column state based on information saved in the
HP TRIM 6 Software Development Kit
Page 275
registry
Move Visual Basic Runtime-Only Extender method
SaveColumnState Save the column state to the registry
SetFocus Visual Basic Runtime-Only Extender method
ShowWhatsThis Visual Basic Runtime-Only Extender method
SortColumn Sort the rows based on a particular column
SwapRows Swap the location of two rows in the control
TagAll Tag or Untag all rows in the control
ZOrder Visual Basic Runtime-Only Extender method
HP TRIM 6 Software Development Kit
Page 276
AddColumn
Adds a column to the control. The column caption and width of the column arespecified.
Syntax[TRIMtreeCol] = TRIMtreeBox.AddColumn (HeadingCaption As String, CharWidth As Long)
Parameters
Name Type Default Description
HeadingCaption String The caption to be displayed on thecolumn header if displayed
CharWidth Long The desired width of the column incharacters
Return Value
Type Description
TRIMtreeColReturns a TRIMtreeCol object on which further refinementscan be made if desired
HP TRIM 6 Software Development Kit
Page 277
AddColumnEx
Adds a column to the control. An expantion on the AddColumn method. The columncaption and width of the column are specified as well as a heading icon.
Syntax[TRIMtreeCol] = TRIMtreeBox.AddColumnEx (HeadingCaption As String, HeadingIcon,CharWidth As Long)
Parameters
Name Type Default Description
HeadingCaption String The caption to be displayed on thecolumn header if displayed
HeadingIcon Variant ***UNDER CONSTRUCTION***
CharWidth Long The desired width of the column incharacters
Return Value
Type Description
TRIMtreeColReturns a TRIMtreeCol object on which further refinementscan be made if desired
HP TRIM 6 Software Development Kit
Page 278
AddManyColumns
Adds a multiple columns to the control. Provides an easy method of adding TRIMcolumns to the control using the PropertyDefs.GetTreeInitString method to get astring in the correct format to pass to this method. See the Remarks area below forthe required format of the string.
Syntax[Long] = TRIMtreeBox.AddManyColumns (Text as String)
Parameters
Name Type Default Description
Text String A string in the format specifed in theRemarks area below
Return Value
Type Description
Long Returns the number of columns added
Remarks
The Text parameter of this method requires a specially formatted string containingTRIM tree box control column information delimited by semi colons.
Required format for the Text parameter:ID|Caption|Width|VisibleState|IconID|Alignment|DisplayMode|IsDefault;NEXT Column
So Each column definition contains the following components delimited by the pipesymbol (|):
Component Description
ID The propertyID that relates to the column
Caption The caption for the column
Width The width of the column in characters
VisibleState 1 = Visible, 2 = Invisible
IconID Specifies the Icon to be displayed in the column header. Mustequate to one of the values specified in the TRIMIconIdenumeration defined in the HP TRIM ActiveX Controls library
Alignment Specifies the alignment of the text within the column. Mustequate to one of the values specified in the tbAlignmentModeenumeration defined in the HP TRIM ActiveX Controls library
DisplayMode Specifies whether text and/or icons can be displayed in therows for this column. Must equate to on of the valuesspecified in the tbDisplayMode enumeration defined in the HPTRIM ActiveX Controls library
IsDefault 1 = true, 0 = false. Only one column per A TRIMtreeBox
HP TRIM 6 Software Development Kit
Page 279
instance can be the default.
Example
The following example passed in as the Text parameter of this method identifies 4columns:1|Record Type|20|1|0|0|3|0;2|Record Number|30|1|0|0|4|1;3|Title|20|1|0|0|4|0;5|DateCreated|20|1|0|0|0|0;
Sample Code
HP TRIM 6 Software Development Kit
Page 280
AddManyRows
Adds multiple rows to the control. Provides an easy method of adding rows thatrepresent TRIM objects to the list area of the control. The GetTreeString methodfound on most TRIM SDK collection objects returns a string in the correct format topass to this method. See the Remarks area below for the required format of thestring. An example code snipit is used to demonstrate how to set up a TRIMtreeBoxcontrol with column headers and rows containing some basic record objectinformation.
Syntax[Long] = TRIMtreeBox.AddManyRows (Text as String)
Parameters
Name Type Default Description
Text String A string in the format specifed in theRemarks area below
Return Value
Type Description
Long Returns the number of rows added
Remarks
The Text parameter of this method requires a specially formatted string containingTRIM tree row information delimited by semi colons.
The required format of this string is detailed in the IbaseObjects.GetTreeStringsection of this help file.
! Note: Care should be taken to ensure that the rows cell contents informationshould match that of the controls columns. If the GetTreeString method is to beused then the PropertyDefs in the Properties Collection should be identical tothat used to get the column information via the GetTreeInitString method.
Sample Code
HP TRIM 6 Software Development Kit
Page 281
AddRow
Adds a row to the control. The Row being added must match the columns in thecontrol. See Remarks, below for the format of the string that represents the row toadd.
Syntax[TRIMtreeRow] = TRIMtreeBox.AddRow (Text As String)
Parameters
Name Type Default Description
Text String A string formatted as indicated in theRemarks area below
Return Value
Type Description
TRIMtreeRowReturns a TRIMtreeRow object which was created as a resultof this method
Remarks
The string required by the Text parameter will be in the following format;CellContents(IconID^Text)|CellContents|Etc
! Note: There must be as many CellContents as there are columns in theTRIMtreeBox control. The Columns must be set up before any Rows are added.
CellContents format
For icon and text: IconID^Text
For Icon Only: IconID^
For Text Only: Text
See also:
AddManyRows
AddManyColumns
HP TRIM 6 Software Development Kit
Page 282
AddRowEx
Adds a row to the control. The Row being added must match the columns in thecontrol. The Uri and Id can also be set along with an indication of wether the rowwill have child row/s.
Syntax[TRIMtreeRow] = TRIMtreeBox.AddRowEx (Text As String, Uri, MayHaveKids As Boolean, Id AsLong, Reserved As Boolean)
Parameters
Name Type Default Description
Text String A string formatted as indicated in the Remarksarea of the AddRow method
Uri Variant A unique identifier for the item this rowrepresents, generally the Uri of the TRIM objectrepresented by this row
MayHaveKids Boolean When set to true the row will be diaplayed witha plus box indicating that it may be ably toexpand and display child rows
Id Long When used with a TRIM object you can use thisproperty to store the type of TRIM object usingvalues from the enumeration:btyBaseObjectTypes. It can also just be used tostore more unique identification for the item thisrow represents
Return Value
Type Description
TRIMtreeRow Returns the TRIMtreeRow object set up by this method
HP TRIM 6 Software Development Kit
Page 283
ClearColumns
Clears the the TRIMtreeBox control. Columns and as a result any existing rows getcleared by this method.
SyntaxTRIMtreeBox.ClearColumns ()
HP TRIM 6 Software Development Kit
Page 284
ClearList
Clears any rows from the control. Columns are left intact by this method.
SyntaxTRIMtreeBox. ClearList ()
HP TRIM 6 Software Development Kit
Page 285
CollapseRow
Causes the row to collapse if it is currently expanded to display any child rows. Thesame method is used when a user clicks on a minus "-" box on an expanded row.This is a way of doing the collapse via code.
SyntaxTRIMtreeBox. CollapseRow (Index As Long)
Parameters
Name Type Default Description
Index Long The index of the row in the TRIMtreeBox thatis to be to acted upon
HP TRIM 6 Software Development Kit
Page 286
CustomizeColumns
Displays the Column Preferences dialog that enables users to configure a number ofthings about how the columns in the TRIMtreeBox are displayed. An example ofsome of the customisation that can be done via this dialog are which columns arevisible, the order of the columns and which columns display icons, text or both.
SyntaxTRIMtreeBox.CustomizeColumns ()
HP TRIM 6 Software Development Kit
Page 287
DeleteColumn
Removes a column from the TRIMtreeBox.
***UNDER CONSTRUCTION***
SyntaxTRIMtreeBox.DeleteColumn (Column)
Parameters
Name Type Default Description
Column Variant Accepts either the column index OR a TRIMtreeCol
HP TRIM 6 Software Development Kit
Page 288
DeleteRow
Removes a row from the control. The index of subsequent rows is moved up to fillthe gap. If the row has child rows these are also removed.
SyntaxTRIMtreeBox.DeleteRow (Index as Long)
Parameters
Name Type Default Description
Index Long The index of the row to be removed
Example
To remove the currently selected row the code would look something like this:TRIMtreeBox1.DeleteRow TRIMtreeBox1.CurrentRow.index
HP TRIM 6 Software Development Kit
Page 289
ExpandRow
Expands the row at the given index if it has child rows. Includes a recursive switchto indicate if chid rows that also have chid rows are to be expanded also. The samebehavour is seen in this control if the user click on a plus "+" box on a row, thoughonly the next level will be expanded with no option fo this behavour to be recursive.
SyntaxTRIMtreeBox.ExpandRow (Index As Long, recursive As Boolean)
Parameters
Name Type Default Description
Index Long Index of the row in the TRIMtreeBox to beexpanded
recursive Boolean Switch that determines if child rows are to beexpanded also
HP TRIM 6 Software Development Kit
Page 290
FindRow
Returns a TRIMtreeRow which matches the passed in search criteria. If a match isfound, then if supplied, foundInRow and foundInColldx will be set to the matchingrow and column indexes. If no match is found, these values will be set to –1.
Syntax[TRIMtreeRow] = TRIMtreeBox.FindRow (SearchString As String, LookInCol, CaseSensitive AsBoolean, PrefixSearch As Boolean, VisibleOnly As Boolean, FoundInRow As Long,FoundInColIdx As Long)
Parameters
Name Type Default Description
SearchString String The string to search for in the textarea of the nominated column
LookInCol Variant The Column in which to search
CaseSensitive Boolean Determines if the search is to becase sensitive or not
PrefixSearch Boolean Determines if an exact match mustbe made or if the results only haveto start with the nominated searchstring
VisibleOnly Boolean Determines if visable rows only arepart of the search or if child rowsthat have been loaded (expandedonce) but are currently collapsedare also searched.
FoundInRow Long – Return Value The index of the first row foundthat matches the search criteria. Ifno match is found the value will beset to –1.
FoundInColIdx Long – Return Value The index of the column in whichthe match was made. If no matchis found the value will be set to –1.
Return Value
Type Description
TRIMtreeRowReturns the first TRIMtreeRow object which matched thesearch criteria
HP TRIM 6 Software Development Kit
Page 291
FindRowEx
Returns a TRIMtreeRow which matches the passed in search criteria. If a match isfound, then if supplied, foundInRow will be set to the matching row index. If nomatch is found, foundInRow will be set to –1.
Syntax[TRIMtreeRow] = TRIMtreeBox.FindRowEx (SearchUri, AnId As Long, FoundInRow As Long)
Parameters
Name Type Default Description
SearchUri Variant The Uri to search for in the Uri property of theTRIMtreeRows
AnId Long TRIMtreeRow.Id property criteria for the search.A zero value is ignored, so pass in 0 for thisparameter if you want to search only on the Uri
FoundInRow Long The index of the first row found that matches thesearch criteria. If no match is found the value willbe set to –1.
Return Value
Type Description
TRIMtreeRowThe first TRIMtreeRow object that matched the searchcriteria
HP TRIM 6 Software Development Kit
Page 292
FindRowEx2
Returns a TRIMtreeRow that matches the passed in search criteria. The search canbe started on the row after the last row that matched the search criteria. Thismethod would be used where the Uri and Id of the rows might not be unique and allrows that match the search criteria should be found. If a match is found, thenfoundInRow will be set to the matching row index. If no match is found, foundInRowwill be set to –1.
Syntax[TRIMtreeRow] = TRIMtreeBox.FindRowEx2 (SearchUri, AnId As Long, FoundInRow As Long,StartFromIndex As Long)
Parameters
Name Type Default Description
SearchUri Variant The Uri to search for in the Uriproperty of the TRIMtreeRows
AnId Long TRIMtreeRow.Id property criteriafor the search. A zero value isignored, so pass in 0 for thisparamater if you want to searchonly on the Uri
FoundInRow Long – Return Value The index of the first row foundthat matches the search criteria.If no match is found the value willbe set to –1.
StartFromIndex Long The row index on which to startthe search
Return Value
Type Description
TRIMtreeRowThe first TRIMtreeRow object which matched the searchcriteria
HP TRIM 6 Software Development Kit
Page 293
GetFirstColumn
Returns the first column starting from on the left side of the TRIMtreeBox control.
Syntax[TRIMtreeCol] = TRIMtreeBox.GetFirstColumn ()
Return Value
Type Description
TRIMtreeCol The first TRIMtreeCol object
See also:
GetNextColumn
HP TRIM 6 Software Development Kit
Page 294
GetFirstRow
Returns the first row in the TRIMtreeBox control (The first tagged row depending onthe value set for the onlyTagged parameter) and sets up the iteration of the rows(GetNextRow) to return all rows ao just the tagged rows.
Syntax[TRIMtreeRow] = TRIMtreeBox.GetFirstRow (onlyTagged As Boolean, Reserved As Boolean)
Parameters
Name Type Default Description
OnlyTagged Boolean Determines if the iteration will return just taggedrows or all rows
Reserved Boolean Reserved for future use, set to False
Return Value
Type Description
TRIMtreeRow The first TRIMtreeRow object
Remarks
Known limitation: It is not safe to modify the ID or URI of a TRIMtreeRow whilstinside a GetFirstRow / GetNextRow loop if the onlyTagged parameter is set to true.
See also:
GetNextRow
HP TRIM 6 Software Development Kit
Page 295
GetNextColumn
Returns the next column in the TRIMtreeBox control. Used after the GetFirstColumnmethod has been called. The returned TRIMtreeCol object will be nothing if all of thecolumns have been returned. GetFirstColumn is then required to reset the iterationback to the beginning of the columns.
Syntax[TRIMtreeCol] = TRIMtreeBox.GetNextColumn ()
Return Value
Type Description
TRIMtreeCol The next TRIMtreeCol object
Example
To loop through all the columns in the TRIMtreeBox control the Visual Basic codemight look something like this:Dim MyTRIMtreeCol As TRIMOCXLib.TRIMtreeCol
'// Get the first columnSet MyTRIMtreeCol = TRIMtreeBox1.GetFirstColumn
'// Loop until the returned column object is nothingDo Until MyTRIMtreeCol Is Nothing
'// Perform an action on each columnMsgBox MyTRIMtreeCol.Caption'// Get the next columnSet MyTRIMtreeCol = TRIMtreeBox1.GetNextColumn
Loop
HP TRIM 6 Software Development Kit
Page 296
GetNextRow
Returns the next row or the next tagged row in the TRIMtreeBox control. Whertherit gets just tagged or all rows is dependent on what was specified when theGetFirrstRow method was called. The GetFirstRow method must be called prior tocallin this method. The returned TRIMtreeRow object will be nothing if all of therows have been returned. GetFirstRow is then required to reset the iteration back tothe beginning of the rows.
Syntax[TRIMtreeRow] = TRIMtreeBox.GetNextRow ()
Return Value
Type Description
TRIMtreeRow Returns the TRIMtreeRow object set up by this method
Remarks
Known limitation: It is not safe to modify the ID or URI of a TRIMtreeRow whilstinside a GetFirstRow / GetNextRow loop if the GetFirstRow onlyTagged parameterwas set to true.
Example
To loop through all the rows in the TRIMtreeBox control the Visual Basic code mightlook something like this:Dim MyTRIMtreeRow As TRIMOCXLib.TRIMtreeRow
'// Get the first Row'// In this case the onlyTagged parameter is set to False to return all rows not just
the tagged ones)Set MyTRIMtreeRow = TRIMtreeBox1.GetFirstRow(False, False)
'// Loop until the returned row object is nothingDo Until MyTRIMtreeRow Is Nothing
'// Perform an action on each columnMsgBox MyTRIMtreeRow.index'// Get the next rowSet MyTRIMtreeRow = TRIMtreeBox1.GetNextRow
Loop
Have a look at the Sample Code in the "Private Sub Command2_Click()" procedureto see another example.
HP TRIM 6 Software Development Kit
Page 297
GetRow
Returns the row in the TRIMtreeBox control with the specified index.
Syntax[TRIMtreeRow] = TRIMtreeBox.GetRow (Index As Long)
Return Value
Type Description
TRIMtreeRow TRIMtreeRow object
HP TRIM 6 Software Development Kit
Page 298
GetRowRect
Returns the first rectangle that is the boundary of the row.
Syntax[Long] = TRIMtreeBox.GetFirstRow (RowIdx As Long, Left As Long, Top As Long, Right AsLong, Bottom As Long)
Parameters
Name Type Default Description
RowIdx Long The index of the row the rectangle isrequired for
Left Long – Return Value The left hand side of the rectangle
Top Long – Return Value The top of the rectangle
Right Long – Return Value The right side of the rectangle
Bottom Long – Return Value The bottom of the rectangle
Return Value
Type Description
Long ***UNDER CONSTRUCTION***
HP TRIM 6 Software Development Kit
Page 299
InsertRow
Inserts a row at the nominated index and returns the TRIMtreeRow object created.
Syntax[TRIMtreeRow] = TRIMtreeBox.InsertRow (Index As Long, Text As String)
Parameters
Name Type Default Description
Index Long The index on the TRIMtreeBox that the row is to beinserted
Text String A String in the format specified in the remarks belowcontaining data to use in the creation of the row
Return Value
Type Description
TRIMtreeRow The TRIMtreeRow object created
Remarks
The string required in the Text parameter needs to be in the following format;CellContents(IconID^Text)|CellContents|Etc
! Note: There must be as many CellContents as there are columns in theTRIMtreeBox control. The Columns must be set up before any Rows are added.
CellContents format
For icon and text: IconID^Text
For Icon Only: IconID^
For Text Only: Text
See also:
InsertRowEx
HP TRIM 6 Software Development Kit
Page 300
InsertRowEx
Inserts a row at the nominated index and returns the TRIMtreeRow object created.It allows for the Uri and/or Id properties of the row to be set along with an indicationof whether the row may have child rows.
Syntax[TRIMtreeRow] = TRIMtreeBox.InsertRowEx (Index As Long, Text As String, Uri, MayHaveKidsAs Boolean, Id As Long, Reserved As Boolean)
Parameters
Name Type Default Description
Index Long The index on the TRIMtreeBox that the row is tobe inserted
Text String The data used in the creation of the row. Therequired format for this paramater can be seenin the Remarks area of the InsertRow method
Uri Variant The Uri to set as the Uri property for this row
MayHaveKids Boolean Determines if a plus "+" box is to be displayedagainst this row that indicates the row may havechild rows
Id Long The value that is set as the Id property of therow
Reserved Boolean Reserved for future use. Set this value to False
Return Value
Type Description
TRIMtreeRow The TRIMtreeRow object created
HP TRIM 6 Software Development Kit
Page 301
LoadColumnState
Loads a saved column state from the registry key stored in the RegKey property ofthe TRIMtreeBox control. Once the column state is loaded it cannot be loaded againduring the lifetime of the control. It does not add columns to the control it merelyreturns them to the last saved state. If the column state information saved does notmatch the current columns in the control, nothing will happen and the return valuewill be False.
Syntax[Boolean] = TRIMtreeBox. LoadColumnState ()
Return Value
Type Description
Boolean Indicates if the method was successful
Remarks
Columns must be added to the control before calling this method.
HP TRIM 6 Software Development Kit
Page 302
SaveColumnState
Saves the current column state into the registry key stored in the RegKey propertyof the TRIMtreeBox control.
Syntax[Boolean] = TRIMtreeBox.SaveColumnState ()
Return Value
Type Description
Boolean Indicates if the method was successful
Remarks
A possible reason for this method to fail might be inadequate permissions to thesystem registry current user area.
HP TRIM 6 Software Development Kit
Page 303
SortColumn
Sorts the rows in the TRIMtreeBox using the specified column and direction. Thismethod is dependent on the value of the property AllowSort being True.
SyntaxTRIMtreeBox.SortColumn (Column, ascending As Boolean, SortCurrentRows As Boolean)
Parameters
Name Type Default Description
Column Variant The column to sort by specified by eitherindex or TRIMtreeCol object
Ascending Boolean Determines the direction of the sort
SortCurrentRows Boolean ***UNDER CONSTRUCTION***
HP TRIM 6 Software Development Kit
Page 304
SwapRows
Swaps the position of two rows in the TRIMtreeBox. This fuction can be used to dosorting outside the scope of the column sorting native to the control.
SyntaxTRIMtreeBox.SwapRows (Index1 As Long, Index2 As Long)
Parameters
Name Type Default Description
Index1 Long Index of one of the rows to be swapped
Index2 Long Index of the other row to be swapped
Remarks
To avoid concusion and unexpected results, ensure that the rows are collapsedbefore using this method.
HP TRIM 6 Software Development Kit
Page 305
TagAll
Tag or untag all rows in the TRIMtreeBox control depending on the specified taggedstate.
SyntaxTRIMtreeBox.TagAll (NewTagState As Boolean)
Parameters
Name Type Default Description
NewTagState Boolean Determines if all rows will be tagged (True) oruntagged (False)
Remarks
Sets the TagNewRows property to the same as the NewTagState parameter. So if allrows are tagged, any new rows added to the TRIMtreeBox will also be tagged. If allrows have been untagged then any new rows added to the TRIMtreeBox are nottagged.
HP TRIM 6 Software Development Kit
Page 306
Events
Name Description
AboutToExpand Occurs if the row should be expanded
AboutToSort Occurs if a sort is about to be carried out
BreakTriggered Occurs if user pressed 'Break' key whilst doing a sort.
ColMadeVisible Occurs if a column has been added to the active list
ContextMenu Occurs if the Windows context menu event occurs
DelKeyPressed Occurs if the Delete key has been pressed
FileDropped ***UNDER CONSTRUCTION***
LButtonClick Occurs if the left mouse button is clicked
LButtonDblClick Occurs if the left mouse button is double clicked
MenuItemEnable For Internal Use Only
MenuItemSelected For Internal Use Only
OLEDragDrop ***UNDER CONSTRUCTION***
OLEDragOver ***UNDER CONSTRUCTION***
OLEStartDrag ***UNDER CONSTRUCTION***
PrefixOkForColumn Occurs just before the popup dialog appears.
PrefixOutOfRange Occurs if prefix was out of range and opted to reselect.
RButtonClick Occurs if the right mouse button is clicked
RButtonDblClick Occurs if the right mouse button is double clicked
RoomForRowsOccurs if the control is not "Full" and there is space formore rows
SelectionChanged Occurs if the selected row changes
SortCompare ***UNDER CONSTRUCTION***
TagChanged Occurs if the tagged state of a row changes
TimerTriggered ***UNDER CONSTRUCTION***
TopSelChanged Occurs if the top most visible row changes
HP TRIM 6 Software Development Kit
Page 307
AboutToExpand
Occurs if the plus "+" box has been clicked indicating that the row should beexpanded to display any child rows. Also occurs as a result of the ExpandRowmethod.
SyntaxTRIMtreeBox_AboutToExpand (Row As TRIMtreeRow)
Parameters
Name Type Default Description
Row TRIMtreeRow The row which is about to expand
Remarks
This event can be used to test the current row to see if it has already beenexpanded, and if not the appropriate caod can be executed to load in any child rows.
Check out the Code Sample "Private Sub TRIMtreeBox1_AboutToExpand" for anexample use of this event.
HP TRIM 6 Software Development Kit
Page 308
AboutToSort
Occurs if a column header is clicked by the user indicating that they want to sort therows using the data in the selected column.
SyntaxTRIMtreeBox_AboutToSort (Col As TRIMtreeCol, ascending As Boolean, SortCurrentRows AsBoolean, Allow As Boolean)
Parameters
Name Type Default Description
Col TRIMtreeCol The column on which the sort is based
ascending Boolean Indicates the direction of the sort
SortCurrentRows Boolean ***UNDER CONSTRUCTION***
Allow Boolean Indicates if the sort is to go ahead
Remarks
This event can be used enable the parent application code to do the sorting (usingthe SwapRows method to get rows in the right order) rather than the controlsinternal sorting. If the parent application did the sort the Allow parameter should beset to False to prevent the controls internal search from being executed.
HP TRIM 6 Software Development Kit
Page 309
BreakTriggered
Occurs if the user pressed the 'Break' key whilst doing a sort.
SyntaxTRIMtreeBox_ BreakTriggered ()
HP TRIM 6 Software Development Kit
Page 310
ColMadeVisible
Occurs if a column is added to the Active Columns in the Column Preferences dialogdisplayed using the CustomizeColumns method and OK is clicked. This event willoccur for each column made visable if more than one column is added to the ActiveColumns list.
SyntaxTRIMtreeBox_ColMadeVisible (Col As TRIMtreeCol, CellNumber As Long)
Parameters
Name Type Default Description
Col TRIMtreeCol The column about to be made visable
CellNumber Long The cell number of the column
HP TRIM 6 Software Development Kit
Page 311
ContextMenu
Occurs if either the right mouse button is clicked on a row or if SHIFT + F10 wasused on the keyboard (Windows standards for context menues) while a row wasselected and the control had focus.
Syntax
TRIMtreeBox_ContextMenu (Row As TRIMtreeRow, WithMouse As Boolean)
Parameters
Name Type Default Description
Row TRIMtreeRow The row on which the event occurred
WithMouse Boolean Indicates that the event occurred using themouse
Remarks
Generally, code to display a popup menu would be called as a result of this event.The WithMouse property can be tested because if this event has occurred because ofkeyboard input the location of the popup menu will need to be determined so that itappears in the correct place.
HP TRIM 6 Software Development Kit
Page 312
DelKeyPressed
Occurs if the Delete (Del) key is pressed while a row is selected and the control hasfocus.
SyntaxTRIMtreeBox_DelKeyPressed (Row As TRIMtreeRow)
Parameters
Name Type Default Description
Row TRIMtreeRow The selected row
Remarks
This event can be used call code to remove the selected row if appropriate.
HP TRIM 6 Software Development Kit
Page 313
FileDropped
Occurs if a or some files have been dropped onto a row in the control.
***UNDER CONSTRUCTION***
SyntaxTRIMtreeBox_FileDropped (OverRow As TRIMtreeRow, FileList As String, FileCount As Long)
Parameters
Name Type Default Description
Row TRIMtreeRow The selected row
HP TRIM 6 Software Development Kit
Page 314
LButtonClick
Occurs if the left mouse button is clicked while on a row in the control.
SyntaxTRIMtreeBox_LButtonClick (Row As TRIMtreeRow)
Parameters
Name Type Default Description
Row TRIMtreeRow The row on which the left click occured
HP TRIM 6 Software Development Kit
Page 315
LButtonDblClick
Occurs if the left mouse button is double clicked while on a row in the control.
SyntaxTRIMtreeBox_LButtonDblClick (Row As TRIMtreeRow)
Parameters
Name Type Default Description
Row TRIMtreeRow The row on which the left click occured
HP TRIM 6 Software Development Kit
Page 316
MenuItemEnable
For Internal Use Only.
SyntaxTRIMtreeBox_MenuItemEnable (Id As Long, Handled As Boolean, ShouldEnable As Boolean)
Parameters
Name Type Default Description
Id Long Reserved
Handled Boolean Reserved
ShouldEnable Boolean Reserved
Remarks
This event is reserved for internal use.
HP TRIM 6 Software Development Kit
Page 317
MenuItemSelected
For Internal Use Only.
SyntaxTRIMtreeBox_MenuItemSelected (Id As Long, Handled As Boolean)
Parameters
Name Type Default Description
Id Long Reserved
Handled Boolean Reserved
ShouldEnable Boolean Reserved
Remarks
This event is reserved for internal use.
HP TRIM 6 Software Development Kit
Page 318
OLEDragDrop
***UNDER CONSTRUCTION***
SyntaxTRIMtreeBox_OLEDragDrop (OverRow As TRIMtreeRow, SrcUri, SrcType As Long, Effect As Long,State As Long, X As Long, Y As Long)
Parameters
Name Type Default Description
OverRow TRIMtreeRow Reserved
SrcUri Variant Reserved
SrcType Long Reserved
Effect Long Reserved
State Long Reserved
X Long Reserved
Y Long Reserved
Remarks
This event is reserved for future use.
HP TRIM 6 Software Development Kit
Page 319
OLEDragOver
***UNDER CONSTRUCTION***
SyntaxTRIMtreeBox_OLEDragOver (OverRow As TRIMtreeRow, SrcUri, SrcType As Long, Effect As Long,State As Long, X As Long, Y As Long)
Parameters
Name Type Default Description
OverRow TRIMtreeRow Reserved
SrcUri Variant Reserved
SrcType Long Reserved
Effect Long Reserved
State Long Reserved
X Long Reserved
Y Long Reserved
Remarks
This event is reserved for future use.
HP TRIM 6 Software Development Kit
Page 320
OLEStartDrag
***UNDER CONSTRUCTION***
SyntaxTRIMtreeBox_OLEStartDrag (DragRow As TRIMtreeRow, Effect As Long)
Parameters
Name Type Default Description
DragRow TRIMtreeRow Reserved
Effect Long Reserved
Remarks
This event is reserved for future use.
HP TRIM 6 Software Development Kit
Page 321
PrefixOkForColumn
Occurs if the user starts typing while the control has focus. The prefix behavior canjump to the row in which the sort column has a value that starts with the keypressed. It can also display a dialog that enables the user to enter more than onecharacter to be used as the prefix. The behavior is determined by the value of theparameters at the end of the event.
Prefix Search dialog:
SyntaxTRIMtreeBox_PrefixOkForColumn (PrefixCol As TRIMtreeCol, PrefixOK As Boolean,PrefixReselectOK As Boolean)
Parameters
Name Type Default Description
PrefixCol TRIMtreeCol The column on which the prefix search isbeing carried out
PrefixOK Boolean Determines if the Prefix Search dialogshould be allowed to appear
PrefixReselectOK Boolean Determines if the user may reselect aprefix if the one they have given is outof range.
Remarks
This event can be used to enable the appropriate behavour depending on the currentsort column.
HP TRIM 6 Software Development Kit
Page 322
PrefixOutOfRange
Occurs if the prefix search can find no matches, and user opts to reselect by a newprefix. This allows the list to be repopulated based on a new prefix.
SyntaxTRIMtreeBox.PrefixOutOfRange (PrefixCol As TRIMtreeCol, Prefix As String)
Parameters
Name Type Default Description
PrefixCol TRIMtreeCol The column on which the reselected prefixsearch is being carried out
Prefix String The new prefix to search by
HP TRIM 6 Software Development Kit
Page 323
RButtonClick
Occurs if the right mouse button is clicked while on a row in the control.
SyntaxTRIMtreeBox_RButtonClick (Row As TRIMtreeRow)
Parameters
Name Type Default Description
Row TRIMtreeRow The row on which the left click occurred
Remarks
If you intend to use this event to display a context menu (right mouse button menu)the ContextMenu event may be more appropriate as it occurs with the right mousebutton click and the Windows keyboard shortcut for context menus (SHIFT + F10).
HP TRIM 6 Software Development Kit
Page 324
RButtonDblClick
Occurs if the right mouse button is double clicked while on a row in the control.
SyntaxTRIMtreeBox_ RButtonDblClick (Row As TRIMtreeRow)
Parameters
Name Type Default Description
Row TRIMtreeRow The row on which the left click occurred
HP TRIM 6 Software Development Kit
Page 325
RoomForRows
Occurs if there is room in the control for more rows to be added and the Fullproperty is False. When filling the TRIMtreeBox control it can be advantageous toreturn control to the user as soon as there are enough loaded rows to be useful andonly return to get more rows when the user has scrolled down, activating this event.
SyntaxTRIMtreeBox_ RoomForRows (Count As Long)
Parameters
Name Type Default Description
Count Long The number of rows available to be filled in thecontrol
Remarks
See the GetTreeString method which can be used to return a specified number ofrows.
See the Visual Basic Sample Code for an example of how to use this event toadvantage.
HP TRIM 6 Software Development Kit
Page 326
SelectionChanged
Occurs if a different row is selected.
SyntaxTRIMtreeBox_SelectionChanged ()
HP TRIM 6 Software Development Kit
Page 327
SortCompare
Occurs if the column's SortMode property is set to tbsmOwnerEvent. This enablessort comparison to take place.
SyntaxTRIMtreeBox_SortCompare (Col As TRIMtreeCol, RowA As TRIMtreeRow, RowB As TRIMtreeRow,AlessThanB As Boolean)
Parameters
Name Type Default Description
Col TRIMtreeCol Column to perform sort on
RowA TRIMtreeRow A nominated row to compare with RowB
RowB TRIMtreeRow A nominated row to compare with RowA
AlessThanB Boolean Determines the sort order of the twospecified rows. Should be set to true ifrowA < rowB.
HP TRIM 6 Software Development Kit
Page 328
TagChanged
Occurs if the tagged state of a row is changed.
SyntaxTRIMtreeBox_TagChanged (Row As TRIMtreeRow)
Parameters
Name Type Default Description
Row TRIMtreeRow The row whose tagged state has changed
HP TRIM 6 Software Development Kit
Page 329
TimerTriggered
For Internal Use Only.
SyntaxTRIMtreeBox_TimerTriggered (Id as Long)
Parameters
Name Type Default Description
Id Long Reserved.
Remarks
This event is reserved for internal use.
HP TRIM 6 Software Development Kit
Page 330
TopSelChanged
Occurs if the visible top row changes, usually caused by the user scrolling up ordown in the TRIMtreeBox control.
SyntaxTRIMtreeBox_TopSelChanged ()
HP TRIM 6 Software Development Kit
Page 331
Other Objects Used by the ActiveX Controls
The TRIMOXCLib containes objects other than the activeX controls. These objectsare used by the activeX controls.
Name Used By
TRIMdateTime TRIMedit
TRIMfavorites Reserved
TRIMtreeCol TRIMtreeBox
TRIMtreeRow TRIMtreeBox
HP TRIM 6 Software Development Kit
Page 332
TRIMdateTime
Used by the TRIMedit control when in date or date time mode, the TRIMdateTimeobject provide an interface to the individual properties of a datetime that can berelevant to the TRIMedit control.
HP TRIM 6 Software Development Kit
Page 333
Properties
Name ``
CannedDate Returns/Sets a canned date
Date ***UNDER CONSTRUCTION***
DateHi ***UNDER CONSTRUCTION***
IgnoreDateReturns/Sets the control to ignore the date component of adate time
IgnoreTimeReturns/Sets the control to ignore the Time component ofa date time
HP TRIM 6 Software Development Kit
Page 334
CannedDate
Returns/Sets the canned date value of the TRIMdateTime.
SyntaxTRIMdateTime.CannedDate= [dtCannedDate]
HP TRIM 6 Software Development Kit
Page 335
Date
Returns/Sets the date value of the TRIMdateTime.
SyntaxTRIMdateTime.Date = [Date]
HP TRIM 6 Software Development Kit
Page 336
DateHi
Returns/Sets.
***UNDER CONSTRUCTION***
SyntaxTRIMdateTime.DateHi = [Date]
HP TRIM 6 Software Development Kit
Page 337
IgnoreDate
Returns/Sets a switch on the TRIMdateTime to ignore the Date component of aDateTime. This enables the TRIMdateTime to be a used to set and return timevalues.
SyntaxTRIMdateTime. IgnoreDate = [Boolean ]
HP TRIM 6 Software Development Kit
Page 338
IgnoreTime
Returns/Sets a switch on the TRIMdateTime to ignore the Time component of aDateTime. This enables the TRIMdateTime to be a used to set and return datevalues.
SyntaxTRIMdateTime. IgnoreTime = [Boolean]
HP TRIM 6 Software Development Kit
Page 339
TRIMfavorites
Reserved. This object class is not currently in use.
HP TRIM 6 Software Development Kit
Page 340
TRIMtreeCol
The TRIMtreeCol object represents a column in the TRIMtreeBox control. It is usedto hold information about a particular column of the TRIMtreeBox control and can bepassed to some TRIMtreeRow methods that require a cell or column identifier.
HP TRIM 6 Software Development Kit
Page 341
Properties
Name ``
Alignment The alignment of text in this column
Caption The text to display in the header
CharWidth The width of the column in characters
DisplayMode Returns/Sets what gets displayed in this column
EllipsisReturns/Sets a value that determines if ellipsis are displayed ifthe text in this column does not fit in the size
Id Returns the identifier for this column
Index Returns the index of the column
IsDefault Returns/Sets the default status for the column
SizeableReturns/Sets a value that determines if the columns width canbe customized
SortMode Returns/Sets the type of sort to perform on this column
SortState Returns/Sets the direction a sort is carried out in
Visible Returns/Sets the visible state for this column
VisibleModeReturns/Sets a value that determines if the user can see orremove a column
Width Returns/Sets the width in pixels
HP TRIM 6 Software Development Kit
Page 342
Alignment
Returns/Sets a value that determines if the text in this column is left aligned, rightaligned or centred in the column.
SyntaxTRIMtreeCol.Alignment = [tbAlignmentMode]
HP TRIM 6 Software Development Kit
Page 343
Caption
Returns/Sets the text to display as the column header. The caption is only displayedif the TRIMtreeBox.Heading property is set to True (Its default state).
SyntaxTRIMtreeCol.Caption= [String]
HP TRIM 6 Software Development Kit
Page 344
CharWidth
Returns/Sets the width of the column in characters.
SyntaxTRIMtreeCol.CharWidth = [Long]
HP TRIM 6 Software Development Kit
Page 345
DisplayMode
Returns/Sets a value that determines if the column will display Icons, Text or both.
SyntaxTRIMtreeCol.DisplayMode = [tbDisplayMode]
HP TRIM 6 Software Development Kit
Page 346
Ellipsis
Returns/Sets a value that determines if ellipsis (…) will be displayed if the text in acolumn does not all fit.
SyntaxTRIMtreeCol.Ellipsis = [tbEllipsisMode]
HP TRIM 6 Software Development Kit
Page 347
Id
Returns/Sets a value that is used as an identifier for the column. This could be setto the property Id of the property being displayed in this column.
SyntaxTRIMtreeCol.Alignment = [String]
HP TRIM 6 Software Development Kit
Page 348
Index (Read Only)
Returns a value that is the current index for the column.
Syntax[Long] = TRIMtreeCol. Index
HP TRIM 6 Software Development Kit
Page 349
IsDefault
Returns/Sets a value that determines the default status of the column. Only onecolumn in a TRIMtreeBox can be the default. Setting this to true on a column setsthe same property to false on all other columns available to the TRIMtreeBox. Beingthe default column means that any sorting that is done is carried out on the values inthis column. The user at runtime can change the value of this property by clickingon a column header.
SyntaxTRIMtreeCol.IsDefault = [Boolean]
HP TRIM 6 Software Development Kit
Page 350
Sizeable
Returns/Sets a value that determines if the columns width can be customized atruntime.
SyntaxTRIMtreeCol.Alignment = [tbAlignmentMode]
HP TRIM 6 Software Development Kit
Page 351
SortMode
Returns/Sets a value that determines the type of sorting that is applied to thiscolumn. Setting this property to have a value of tbsmOwnerEvent will cause theTRIMtreeBox_ SortCompare event to fire which in turn can be caught and somecustomized sorting code executed.
SyntaxTRIMtreeCol.SortMode= [tbSortMode]
HP TRIM 6 Software Development Kit
Page 352
SortState
Returns/Sets a value that determines if the column is sorted in ascending ordescending order or if in fact it is sorted at all.
SyntaxTRIMtreeCol.SortState = [tbSortState]
HP TRIM 6 Software Development Kit
Page 353
Visible
Returns/Sets a value that determines if the column is displayed.
SyntaxTRIMtreeCol.Visible = [Boolean]
HP TRIM 6 Software Development Kit
Page 354
VisibleMode
Returns/Sets a value that determines if the column is hidden from the usercompletely, must be displayed in the TRIMtreeBox (cannot be removed from theactive list by the user when customizing columns) or is not hidden from the user noris it mandatory for it to be displayed.
SyntaxTRIMtreeCol.VisibleMode = [tbVisibleMode]
HP TRIM 6 Software Development Kit
Page 355
Width (Read Only)
Returns a value that is the columns width in pixels.
SyntaxTRIMtreeCol.Width = [Long]
HP TRIM 6 Software Development Kit
Page 356
Methods
Name ``
SetIcon Sets the icon to use in this column
HP TRIM 6 Software Development Kit
Page 357
SetIcon
Sets the Icon to be used in this column.
Syntax[Boolean] = TRIMtreeCol. SetIcon (Icon)
Parameters
Name Type Default Description
Icon Variant ***UNDER CONSTRUCTION***
Return Value
Type Description
Boolean Returns the success of the method
HP TRIM 6 Software Development Kit
Page 358
TRIMtreeRow
The TRIMtreeRow object represents a row in the TRIMtreeBox control. It is used tohold row information and provides a way of manipulating details of a row.TRIMtreeRows may have child rows and it is through a TRIMtreeRow object thataccess to the child rows can be found.
HP TRIM 6 Software Development Kit
Page 359
Properties
Name ``
AutoRedrawReturns/Sets a value that determines if auto redrewar isenabled
BoldReturns/Sets a value that determines if the font appearsbold in the row
Enabled Returns/Sets a value that determines if the row is enabled
EverExpandedReturns a value that indicates if the row has ever beenexpanded
ExpandedReturns a value that indicates if the row is currentlyexpanded
ExpandLockedReturns/Sets a value that determines if the row can beexpanded or collapsed
Id Returns/Sets an identifier value on the row
Index Returns a value that indicates the position in the list
MayHaveKidsReturns/Sets a value that indicates that the row may be aparent row
RowTextReturns/Sets a specially formatted string that gets or setsthe icon and test values of the cells
Tagged Returns/Sets the tagged state of the row
TagStateLockedReturns/Sets a boolean that determines if a user can tagor untag a row through the user interface
Uri Returns/Sets a unique identifier
Visible Returns/Sets the visible state of the row
HP TRIM 6 Software Development Kit
Page 360
AutoRedraw
Returns/Sets a value that determines if auto redrewar is enabled.
SyntaxTRIMtreeRow.AutoRedraw = [Boolean]
HP TRIM 6 Software Development Kit
Page 361
Bold
Returns/Sets a value that determines if the font appears bold in the row.
SyntaxTRIMtreeRow.Bold = [Boolean]
HP TRIM 6 Software Development Kit
Page 362
Enabled
Returns/Sets a value that determines if the row is enabled.
SyntaxTRIMtreeRow.Enabled = [Boolean]
HP TRIM 6 Software Development Kit
Page 363
EverExpanded (Read Only)
Returns a value that indicates if the row has ever been expanded.
SyntaxTRIMtreeRow.EverExpanded = [Boolean]
HP TRIM 6 Software Development Kit
Page 364
Expanded (Read Only)
Returns a value that indicates if the row is currently expanded.
SyntaxTRIMtreeRow.Expanded = [Boolean]
HP TRIM 6 Software Development Kit
Page 365
ExpandLocked
Returns/Sets a value that determines if the row can be expanded or collapsed.
SyntaxTRIMtreeRow. ExpandLocked = [Boolean]
HP TRIM 6 Software Development Kit
Page 366
Id
Returns/Sets an identifier value on the row. For TRIM objects this could indicate theobject type (btyBaseObjectTypes).
SyntaxTRIMtreeRow.Id = [Long]
HP TRIM 6 Software Development Kit
Page 367
Index (Read Only)
Returns a value that indicates the position in the list. This will change for a givenrow if rows are inserted above or a sort is carried out.
SyntaxTRIMtreeRow.Index = [Long]
HP TRIM 6 Software Development Kit
Page 368
MayHaveKids
Returns/Sets a value that indicates that the row may have a/some child row/s. Interms of the user interface a plus (+) box will be displayed on a row whereMayHaveKids = True.
SyntaxTRIMtreeRow.MayHaveKids = [Boolean]
HP TRIM 6 Software Development Kit
Page 369
RowText
Returns/Sets a specially formatted string that gets or sets the icon and test values ofthe cells. See the remarks area of the TRIMtreeBox.AddRow method for the formatof the string.
SyntaxTRIMtreeRow.RowText = [Boolean]
HP TRIM 6 Software Development Kit
Page 370
Tagged
Returns/Sets the tagged state of the row.
SyntaxTRIMtreeRow.Tagged = [Boolean]
HP TRIM 6 Software Development Kit
Page 371
TagStateLocked
Returns/Sets a boolean that determines if a user can tag or untag a row through theuser interface.
SyntaxTRIMtreeRow.TagStateLocked = [Boolean]
HP TRIM 6 Software Development Kit
Page 372
Uri
Returns/Sets a unique identifier of an item that the row data represents. For a TRIMobject this can contain the value from the objects Uri property.
SyntaxTRIMtreeRow.Uri = [Variant]
HP TRIM 6 Software Development Kit
Page 373
Visible
Returns/Sets the visible state of the row.
SyntaxTRIMtreeRow.Visible = [Boolean]
HP TRIM 6 Software Development Kit
Page 374
Methods
Name ``
AddChild Adds a child row to this TRIMtreeRow
AddManyRows Adds many child rows to this TRIMtreeRow
ClearChildren Removes any child rows to this TRIMtreeRow
CollapseRow Collapses this row in the user interface
DeleteChildRow Removes a particular child row
ExpandRow Expands this row in the user interface
GetCellText Gets the text in a particular cell of this TRIMtreeRow
GetFirstRow Gets the first child row of this TRIMtreeRow
GetNextRow Gets the next child row of this TRIMtreeRow
GetParentRow Gets the parent row of this TRIMtreeRow
InsertChild Adds a child row at a specified index
SetCellIconSets the icon to be used in this cell of theTRIMtreeRow
SetCellText Sets the text value of this cell of the TRIMtreeRow
HP TRIM 6 Software Development Kit
Page 375
AddChild
Adds a child row to this TRIMtreeRow.
Syntax[TRIMtreeRow] = TRIMtreeRow.AddChild (Text As String, Uri, MayHaveKids As Boolean, Id AsLong)
Parameters
Name Type Default Description
Text String A string in the format described in the remarkssection of the AddRow method
Uri Variant The unique identifier for the row
MayHaveKids Boolean When set to true the row will be displayed with aplus box indicating that it may be able to expandand display child rows
Id Long When used with a TRIM object you can use thisproperty to store the type of TRIM object usingvalues from the enumeration:btyBaseObjectTypes. It can also just be used tostore more unique identification for the item thisrow represents.
Return Value
Type Description
TRIMtreeRow Returns the row object added as a child to the TRIMtreeRow
See also:
AddManyRows
HP TRIM 6 Software Development Kit
Page 376
AddManyRows
Adds many child rows to the the TRIMtreeRow. Functions in the same way as theAddManyRows method on the TRIMtreeBox control only that the many rows areadded as child rows.
Syntax[TRIMtreeRow] = TRIMtreeRow.AddManyRows (Text As String)
Parameters
Name Type Default Description
Text String A string in the format specifed in theRemarks area below
Return Value
Type Description
Long Returns the number of rows added
Remarks
The Text parameter of this method requires a specially formatted string containingTRIM tree row information delimited by semi colons.
The required format of this string is detailed in the IbaseObjects.GetTreeStringsection of this help file.
! Note: Care should be taken to ensure that the rows cell contents informationshould match that of the controls columns. If the GetTreeString method is to beused then the PropertyDefs in the Properties Collection should be identical tothat used to get the column information via the GetTreeInitString method.
HP TRIM 6 Software Development Kit
Page 377
ClearChildren
Removes any child rows from the TRIMtreeRow.
SyntaxTRIMtreeRow.ClearChildren ()
HP TRIM 6 Software Development Kit
Page 378
CollapseRow
Returns the TRIMtreeRow to an unexpanded state. The same behavior as if the userhas clicked on the minus (-) box on the row in the TRIMtreeBox control. The row iscollapsed and the minus(-) box is replaced with a plus (+) box to indicate the rowmay have child rows and be able to expand.
SyntaxTRIMtreeRow. CollapseRow ()
HP TRIM 6 Software Development Kit
Page 379
DeleteChildRow
Removes the child row at the specified index from the TRIMtreeBox control.
SyntaxTRIMtreeRow. DeleteChildRow (Index as Long)
Parameters
Name Type Default Description
Index Long The index of the child row to remove
HP TRIM 6 Software Development Kit
Page 380
ExpandRow
Expands the TRIMtreeRow to display any child rows. The same behavior as if theuser has clicked on the plus (+) box on the row in the TRIMtreeBox control. The rowis expanded and the plus (+) box is replaced with a minus (-) box to indicate the rowis in an expanded state (or removed if there are no child rows to display).
SyntaxTRIMtreeRow. ExpandRow (recursive As Boolean)
Parameters
Name Type Default Description
recursive Boolean Determines if the ExpandRow function should beapplied to any child rows that may have child rowsin turn (MayHaveKids = true)
HP TRIM 6 Software Development Kit
Page 381
GetCellText
Returns the value as a string of the specified cell from this TRIMtreeRow in theTRIMtreeBox control.
Syntax[String] = TRIMtreeRow.GetCellText (Column)
Parameters
Name Type Default Description
Column Variant Both the column index or a TRIMtreeColobject are accepted
Return Value
Type Description
String The value in the specified cell of the TRIMtreeRow
HP TRIM 6 Software Development Kit
Page 382
GetFirstRow
Returns the first row in the child row iteration. Used with the GetNextRow method toiterate through any child rows. It also indicates if the iteration includes all rows oronly tagged rows and resets the iteration. Similar to the GetFirstRow method on theTRIMtreeBox control.
Syntax[TRIMtreeRow] = TRIMtreeRow.GetFirstRow (onlyTagged As Boolean)
Parameters
Name Type Default Description
onlyTagged Boolean Sets the TRIMtreeRow child row iterationto include all or only tagged rows
Return Value
Type Description
TRIMtreeRow The first row found in the child row iteration
HP TRIM 6 Software Development Kit
Page 383
GetNextRow
Returns the next row in the child row iteration. Used with the GetFirstRow methodto iterate through any child rows. It returns the next child row or the next taggedchild row depending on value of the onlyTagged parameter of the GetFirstRowmethod. Similar to the GetNextRow method on the TRIMtreeBox control.
Syntax[TRIMtreeRow] = TRIMtreeRow. GetNextRow ()
Return Value
Type Description
TRIMtreeRowThe next row found in the child row iteration. If the end of theiteration has been reached the returned TRIMtreeRow will be setto Nothing.
Remarks
The GetFirstRow method must be used prior to using this method in order to set upthe row iteration.
HP TRIM 6 Software Development Kit
Page 384
GetParentRow
Returns the parent row of this TRIMtreeRow.
Syntax[TRIMtreeRow] = TRIMtreeRow. GetParentRow ()
Return Value
Type Description
TRIMtreeRowThe parent TRIMtreeRow. If there is no parent to this row thereturned TRIMtreeRow will be set to Nothing.
HP TRIM 6 Software Development Kit
Page 385
InsertChild
Inserts a child row into the TRIMtreeRow at the specified index.
Syntax[TRIMtreeRow] = TRIMtreeRow. InsertChild (Index As Long, Text As String, Uri, MayHaveKidsAs Boolean, Id As Long)
Parameters
Name Type Default Description
Index Long The location in the child rows to insert the newrow
Text String A string in the format described in the remarkssection of the AddRow method
Uri Variant A unique identifier for the item this rowrepresents, generally the Uri of the TRIM objectrepresented by this row
MayHaveKids Boolean When set to true the row will be diaplayed witha plus box indicating that it may be ably toexpand and display child rows
Id Long When used with a TRIM object you can use thisproperty to store the type of TRIM object usingvalues from the enumeration:btyBaseObjectTypes. It can also just be used tostore more unique identification for the item thisrow represents
Return Value
Type Description
TRIMtreeRow The row iserted
HP TRIM 6 Software Development Kit
Page 386
SetCellIcon
Sets the Icon used in the specified cell of this TRIMtreeRow.
Syntax[Boolean] = TRIMtreeRow.SetCellIcon (Column, Icon)
Parameters
Name Type Default Description
Column Variant Both the column index or a TRIMtreeCol object areaccepted
Icon Variant Both a number representing a value in the TRIMIconIdenumeration or a string that is a file extention knownto the machine are accepted
Return Value
Type Description
Boolean Returns the success of the method
HP TRIM 6 Software Development Kit
Page 387
SetCellText
Sets the text used in the specified cell of this TRIMtreeRow.
Syntax[Boolean] = TRIMtreeRow. SetCellText (Column, Text as String)
Parameters
Name Type Default Description
Column Variant Both the column index or a TRIMtreeCol object areaccepted
Text String The value of the text to be displayed in the specifiedcell
Return Value
Type Description
Boolean Returns the success of the method
HP TRIM 6 Software Development Kit
Page 388
Enumerated Types for ActiveX Controls
Name Description
dtCannedDate TRIM Canned Dates
fvFavoriteType Favorite types
ksBrowseMode Browse Active Modes for a HP TRIM Edit Box
ksCannedDatesMode Canned Date Modes for the contents of a HP TRIM Edit Box
ksEditValidMode Validity Modes for the contents of a HP TRIM Edit Box
ksScrollMode Scroll Bar Modes for HP TRIM Controls
ksSelectMode Select Modes for a HP TRIM Edit Box
tagTRIMIconId HP TRIM Icon IDs
tbAlignmentMode Text Alignment Modes for HP TRIM Tree Column
tbDisplayMode Display mode for HP TRIM Tree Column
tbEllipsisMode Text Ellipsis Modes for HP TRIM Tree Column
tbSortMode Sort Mode for HP TRIM Tree Column
tbSortState Sort State for HP TRIM Tree Column
tbTagMode Tagging Mode for HP TRIM Tree Box
tbVisibleMode Visible Permission status for a HP TRIM Tree Box Column
TRIMIconId HP TRIM Icon IDs
vwDocFormat Document Format Categories displayed in a HP TRIM Viewe
HP TRIM 6 Software Development Kit
Page 389
dtCannedDate
Name Value Description
cd_none 0 None
cd_yesterday 1 Yesterdays date
cd_today 2 PrivateTodays date
cd_tomorrow 3 Tomorrows date
cd_lastWeek 4 The date range for last week
cd_thisWeek 5 The date range for this week
cd_nextWeek 6 The date range for next week
cd_lastMonth 7 The date range for last month
cd_thisMonth 8 The date range forthis month
cd_nextMonth 9 The date range fornext month
cd_this year 10 The date range forthis year
cd_yearToDate 11 The date range for the year to today
cd_last7Days12
The date range that is the last sevendays
cd_next7Days13
The date range that is the next sevendays
cd_last14Days 14 The date range that is the last 14 days
HP TRIM 6 Software Development Kit
Page 390
fvFavoriteType
Name Value Description
fvNormal0
The appropriate favourite tray for theobject type
fvWorktray1
Users worktray, records are manuallyadded and removed from this tray
fvRecentDocuments2
Tray containing any recient documents(records with electronic attachments)
fvRecentFolders3
Tray containing any recient folders (Recordswith contained records)
HP TRIM 6 Software Development Kit
Page 391
ksBrowseMode
Name Value Description
ksBrowseDisabled 0 Disabled
ksBrowseActive 1 Active
ksBrowseEvenLocked 2 Browse active even when locked
HP TRIM 6 Software Development Kit
Page 392
ksCannedDatesMode
Name Value Description
cdNone 0 No Canned dates
cdAll 1 All canned dates available for selection
cdNoRanges2
All canned dates available for selectionexcept date ranges
cdOnlyFuture3
Only future canned dates available forselection
cdOnlyFutureNoRanges4
Only future canned dates available forselection excluding date ranges
HP TRIM 6 Software Development Kit
Page 393
ksEditValidMode
Name Value Description
ksUnknown -1 Unknown
ksNotValidated 0 Invalid
ksValid 1 Valid
ksAmbiguous 2 Ambiguous
HP TRIM 6 Software Development Kit
Page 394
ksScrollMode
Name Value Description
ksNone 0 No Scroll bars
ksHoriz 1 Horizontal scroll bar
ksVert 2 Vertical scroll bar
ksBoth 3 Both horizontal and vertical scroll bars
HP TRIM 6 Software Development Kit
Page 395
ksSelectMode
Name Value Description
ksBrowse0
Browse mode, (Kwick select icon, user definedfunction)
ksSpell 1 Invoke Spell Check
ksDir 2 Browse for directory (Select directory)
ksFileIn 3 Browse for input file (Select file)
ksFileOut4
Browse for output file (Select directory and enterfile name or select an existing file)
ksDateTime 5 Date and Time mode (Includes calander control)
KsDate 6 Date mode (Includes calander control)
KsFormat7
Format mode (ellipsis icon, user definedfunction)
HP TRIM 6 Software Development Kit
Page 396
tbAlignmentMode
Name Value Description
tbaLeft 0 Align Left
tbaRight 1 Align Right
tbaCenter 2 Align Centre
HP TRIM 6 Software Development Kit
Page 397
tbDisplayMode
Name Value Description
tbdmTextOnly 0 Display text only
tbdmIconOnly 1 Display the icon only
tbdmText 2 Display text
tbdmIcon 3 Display icon
tbdmBoth 4 Display both the text and icon
HP TRIM 6 Software Development Kit
Page 398
tbEllipsisMode
Name Value Description
tbeNone 0 No ellipsis
tbeRight1
Ellipsis displayed to the right of the text when itdoes not fit in the display area
HP TRIM 6 Software Development Kit
Page 399
ltbSortMode
Name Value Description
tbsmNone 0 No sort mode
tbsmAlphaNoCase 1 Sort alphabetically ignore case
tbsmAlphaCase 2 Sort alphabetically case sensitive
tbsmNumeric 3 Sort numerically
tbsmIcon 4 Sort by icon
tbsmOwnerEvent5
Causes the SortCompare Event to fire onthe TRIMtreeBox control
tbsmDate 6 Sort by Date
tbsmTime 7 Sort by Time
tbsmDateTime 8 Sort by Date and Time
tbsmFileSize 9 Sort by file size
tbsmAlphaNoCaseEnhanced10
Sort alphabetically case sensitive withenhanced numbers
tbsmAlphaCaseEnhanced11
Sort alphabetically ignore case withenhanced numbers
tbsmCurrency 12 Sort by Currency
HP TRIM 6 Software Development Kit
Page 400
tbSortState
Name Value Description
tbssUnsorted 0 Unsorted
tbssAscending 1 Sort Ascending
tbssDescending 2 Sort Descending
HP TRIM 6 Software Development Kit
Page 401
tbTagMode
Name Value Description
tbtmDisabled 0 Tagging disabled
tbtmTags 1 Tagging enabled
HP TRIM 6 Software Development Kit
Page 402
tbVisibleMode
Name Value Description
tbvEither0
Can be hidden or visable (usersdescretion)
tbvHidden 1 Must be hidden
tbvMandatory 2 Must be visable
HP TRIM 6 Software Development Kit
Page 403
TRIMIconId
Enums representing the icons used in HP TRIM. A description has only beenprovided where the name of the icon is not self explanatory. A Prefix key table hasbeen provided to assist.
Prefix Key
Prefix Description
icon_rty_ Record Type icon
icon_act… Action icon
icon_prc Procedure icon
icon_odma_Icons used in the ODMA (Desktop applications)integration
icon_loc Location icons
icon_loceadd Location electronic address icons
icon_login Location login type icons
icon_rec_in_ Record current location options icons
icon_wkc_doc… Workflow document icons
icon_edm.. Electronic document management icons
icon_sch.. Retention Schedule icons
icon_th… Thesaurus icons
Name Value Description
icon_tower 1 The TOWER icon
icon_topdrawer 2 The TopDrawer icon
icon_trf 3 TRIM Reference icon
icon_viewer 4 TRIM Viewer icon
icon_tick 450 Tick icon
icon_cross 451 Cross icon
icon_noentry 454 Not Allowed icon
icon_rty_yellowfile 502 Record Type Folder icon
HP TRIM 6 Software Development Kit
Page 404
icon_rty_yellowdoc 503 Record Type Document icon
icon_rty_yellowbox 504 Record Type Box icon
icon_rty_yellowbook 505 Record Type Book icon
icon_rty_whitefile 506 Record Type Folder icon
icon_rty_whitedoc 507 Record Type Document icon
icon_rty_whitebox 508 Record Type Box icon
icon_rty_whitebook 509 Record Type Book icon
icon_rty_greenfile 510 Record Type Folder icon
icon_rty_greendoc 511 Record Type Document icon
icon_rty_greenbox 512 Record Type Box icon
icon_rty_greenbook 513 Record Type Book icon
icon_rty_ltbluefile 514 Record Type Folder icon
icon_rty_ltbluedoc 515 Record Type Document icon
icon_rty_ltbluebox 516 Record Type Box icon
icon_rty_ltbluebook 517 Record Type Book icon
icon_rty_dkbluefile 518 Record Type Folder icon
icon_rty_dkbluedoc 519 Record Type Document icon
icon_rty_dkbluebox 520 Record Type Box icon
icon_rty_dkbluebook 521 Record Type Book icon
icon_rty_blackfile 522 Record Type Folder icon
icon_rty_blackdoc 523 Record Type Document icon
icon_rty_blackbox 524 Record Type Box icon
icon_rty_blackbook 525 Record Type Book icon
icon_rty_redfile 526 Record Type Folder icon
icon_actdone 527 Action Done icon
icon_rty_reddoc 527 Record Type Document icon
icon_rty_redbox 528 Record Type Box icon
icon_rty_redbook 529 Record Type Book icon
HP TRIM 6 Software Development Kit
Page 405
icon_rty_greyfile 530 Record Type Folder icon
icon_rty_greydoc 531 Record Type Document icon
icon_rty_greybox 532 Record Type Box icon
icon_rty_greybook 533 Record Type Book icon
icon_rty_pinkfile 534 Record Type Folder icon
icon_rty_pinkdoc 535 Record Type Document icon
icon_rty_pinkbox 536 Record Type Box icon
icon_rty_pinkbook 537 Record Type Book icon
icon_rty_tealfile 538 Record Type Folder icon
icon_rty_tealdoc 539 Record Type Document icon
icon_rty_tealbox 540 Record Type Box icon
icon_rty_tealbook 541 Record Type Book icon
icon_rty_envopen 542 Record Type Open Envelope icon
icon_rty_envclosed 543 Record Type Closed Envelope icon
icon_rty_cd 544 Record Type CD icon
icon_rty_clipboard 545 Record Type Clipboard icon
icon_rty_tape1 546 Record Type Tape icon
icon_rty_tape2 547 Record Type Tape icon
icon_rty_floppy3 548 Record Type Floppy Disk icon
icon_rty_floppy5 549 Record Type Floppy Disk icon
icon_rty_orangefile 550 Record Type Folder icon
icon_rty_orangedoc 551 Record Type Document icon
icon_rty_orangebox 552 Record Type Box icon
icon_rty_orangebook 553 Record Type Book icon
icon_rty_brownfile 554 Record Type Folder icon
icon_rty_browndoc 555 Record Type Document icon
icon_rty_brownbox 556 Record Type Box icon
icon_rty_brownbook 557 Record Type Book icon
HP TRIM 6 Software Development Kit
Page 406
icon_act 570 Action icon #1
icon_action 571 Action icon #2
icon_actdue 573 Action Due icon
icon_actnormal 574 Action Normal icon
icon_actoverdue 575 Action Overdue icon
icon_prcdone 576 Procedure Done icon
icon_prcdue 577 Procedure Due icon
icon_prcnormal 578 Procedure Normal icon
icon_prcoverdue 579 Procedure Overdue icon
icon_procedure 580 Procedure icon
icon_census 585 Census icon
icon_Caveat 590 Security Caveat icon
icon_extrafields 591 Extra Fields icon
icon_lookupsets 592 Lookup Sets icon
icon_securitylevel 593 Security Level icon
icon_webLayouts 594 Web Publisher Layouts icon
icon_searchmethod 600 Search Methods icon
icon_odma_draft 605 ODMA Draft icon
icon_odma_modified 606 ODMA Modified icon
icon_odma_readonly 607 ODMA Read Only icon
icon_odma_unknown 608 ODMA Unknown icon
icon_odma_unmodified 609 ODMA Original icon
icon_class_inactive 615 Class Inactive icon
icon_plannotok 616
icon_fpplans 617 Classification Plan icon
icon_activeloc 620 Location Active icon
icon_localllist 621 Location List icon
icon_contact 622 Contact icon
HP TRIM 6 Software Development Kit
Page 407
icon_loccontactlist 623 Location Contact List icon
icon_locdirectory 624 Internal Directory icon
icon_loceaddrimage 625 Location Address Image icon
icon_loceaddrmail 626 Location Address Mail icon
icon_loceaddrrdn 627
icon_loceaddrurl 628 Location Address URL icon
icon_externalloc 629 Location Extrenal icon
icon_locextlist 630 Location External List icon
icon_extposition 631 External Position icon
icon_group 632 Group icon
icon_groupadhoc 633 Adhoc Group icon
icon_locgroupslist 634 Location Groups List icon
icon_inactiveloc 635 Location Inactive icon
icon_internalloc 636 Location Internal icon
icon_locintlist 637 Location Internal List icon
icon_loginadmin 638 Administration Login icon
icon_logincustom 639 Custom Login icon
icon_logindisabled 640 Disabled Login icon
icon_loginenduser 641 End User Login icon
icon_loginenquiry 642 Enquiry User icon
icon_loginexpired 643 Expired Login icon
icon_loginmanager 644 Information Manager Login icon
icon_loginnone 645 No Login icon
icon_loginworker 646 Information Worker Login icon
icon_org 647 Organization icon
icon_locorglist 648 Local Organization icon
icon_person 649 Person icon
icon_position 650 Position icon
HP TRIM 6 Software Development Kit
Page 408
icon_locposlist 651 Local Position List icon
icon_postalCode 652 Postal Code icon
icon_locstafflist 653 Local Staff List icon
icon_unit 654 Unit icon
icon_locunitlist 655 Location Unit List icon
icon_unknownloc 656 Location Unknown icon
icon_locunknownlist 657 Location Unknown List icon
icon_rec_at_home 660 Record at Home icon
icon_duetray 661 Due Tray icon
icon_edmdocavailable 662Electronic Document ManagementDocument Available icon
icon_edmdoccheckedout 663Electronic Document ManagementDocument Checked Out icon
icon_edmdoccheckedouttoyou 664Electronic Document ManagementDocument Checked Out to You icon
icon_edmnodocument 665Electronic Document ManagementNo Document icon
icon_rec_in_container 666 Record in Container icon
icon_rec_in_space 667 Record in Space icon
icon_intray 668 In Tray icon
icon_induetray 669 In/Due Tray icon
icon_missing 670 Record Missing icon
icon_record 671 Record icon
icon_securitybreach 672 Security Breach icon
icon_worktray 673 WorkTray icon
icon_bpbarcode 680 Barcode icon
icon_rpbitmap 681 Report Layout Bitmap icon
icon_rpcaption 682 Report Layout Caption icon
icon_rp_childlist 683 Report Layout Child List icon
icon_rpfield 684 Report Layout Field icon
HP TRIM 6 Software Development Kit
Page 409
icon_rpline 685 Report Layout Line icon
icon_rpproperty 686 Report Layout Property icon
icon_rprectangle 687 Report Layout Rectangle icon
icon_reports 688 Report Layouts icon
icon_rp_selectors 689 Report Layout Selector icon
icon_rptabstop 690 Report Layout Tab Stop icon
icon_rptext 691 Report Layout Text icon
icon_rty_inactive 699 Record Type Inactive icon
icon_recordtype 700 Record Type icon
icon_active 705 Active icon
icon_archivedfinal 706 Archived Permanent icon
icon_archivedinterim 707 Archived Interim icon
icon_archivedlocal 708 Archived Local icon
icon_cases 709 Cases icon
icon_destroyed 710 Destroyed icon
icon_sch_inactive 711Archive Retention Schedule Inactiveicon
icon_hold_inactive 712 Record Hold Inactive icon
icon_inactive 713 Inacive icon
icon_schlesssevere 714Archive Retention Schedule LessSevere icon
icon_schmaybemoresevere 715Archive Retention Schedule May beMore Severe icon
icon_schmoresevere 716Archive Retention Schedule MoreSevere icon
icon_schedule 717 Archive Retention Schedule icon
icon_space 720 Space Management icon
icon_tdfileview 725 TopDrawer File View icon
icon_tdfolderview 726 TopDrawer Folder View icon
icon_toolstepdone 730 Tool Step Done icon
HP TRIM 6 Software Development Kit
Page 410
icon_toolsteprogress 735 Tool Step Progress icon
icon_thaspect 740 Thesaurus Aspect icon
icon_th_inactive 741 Thesaurus Inactive icon
icon_thkeynode 742 Thesaurus Key Node icon
icon_thkeyword 743 Thesaurus Keyword icon
icon_thlist 744 Thesaurus List icon
icon_thnonpreferred 745 Thesaurus Non-Preferred Term icon
icon_thprompt 746 Thesaurus Prompt icon
icon_thprompttop 747 Thesaurus Prompt Top Term icon
icon_broader 748Thesaurus Broader TermRelationship icon
icon_forbidden 749Thesaurus Forbidden TermRelationship icon
icon_narrower 750Thesaurus Narrower TermRelationship icon
icon_preferred 751Thesaurus Preferred TermRelationship icon
icon_related 752Thesaurus Related TermRelationship icon
icon_thterm 753 Thesaurus Term icon
icon_topforbidden 754 Top Forbidden icon
icon_barcodescanner 760 Barcode Scanner icon
icon_stopword 765 Stop Words icon
icon_edmstore 766 Electronic Domument Store icon
icon_wkc_docoriginactin 770Workflow Originating Document Inicon
icon_wkc_docoriginactout 771Workflow Originating Document Outicon
icon_wkc_docoriginWorkflow 772Workflow Originating Documenticon
icon_wkc_docstatusclear 773Workflow Document Status Clearicon
HP TRIM 6 Software Development Kit
Page 411
icon_wkc_docstatusin 774 Workflow Document Status In icon
icon_wkc_docstatusnone 775Workflow Document Status Noneicon
icon_wkc_docstatustd 776Workflow Document StatusTopDrawer icon
icon_Workflow 779 Workflow icon
icon_Workflowtemplate 805 Workflow Template icon
HP TRIM 6 Software Development Kit
Page 412
vwDocFormat
Name Value Description
vwUnknown 2 Unknown
vwDoc 3 Word Processor
vwSS 4 Spreadsheet
vwDB 5 Database
vwHex 6 Hex
vwImage 7 Raster Image
vwArchive 8 Archive
vwVector 9 Vector image
vwSound 10 Sound
vwMail 11 Mail Message
vwTiff 12 TIF Image
HP TRIM 6 Software Development Kit
Page 413
Property Ids
Unique property identifiers are used by various methods for reading and updatingproperties of an object. The Property Id for a specific property can be discoveredthrough querying the Database within the TRIM SDK.
Sample programs in C# and Visual Basic which use the SDK to generate a table ofProperty Ids are included in the SDK samples section of the HP TRIM CD. Registeredusers may also find these samples on the HP Software Support Online (SSO) portalhttp://support.openview.hp.com/. Click Use self-solve knowledge searchand then search for TRIM SDK.
HP TRIM 6 Software Development Kit
Page 414
What's New from TRIM Captura to the HP TRIM SDK
This section describes the main differences between the TRIM 5.0 interfaces andthose of the TRIM Captura (4.3), for the benefit of programmers required to upgradecode developed against one to the other.
Summary of Changes
Subject Captura TRIM 5 and 6
General
Server Tsapi.exe
Out of process
Trimsdk.dll
In process
Type Libraryname &description
tsapiTRIM 4.3 API Type Library
TRIMSDKTRIM SDK Type Library
Top level object Application object Database object
Object names ITS_ prefix (for example,ITS_record)
No prefix (for example, Record)
Databaseconnection
Explicitapp.Connect(usr, pwd, db)
Automatic to default DBdb.Connect
Instantiatingobjects
obj = Make<object> obj = Get<object>
Instantiatingobjects by URI
obj.Lookup(123) obj = GetRecord(123)
Instantiatingobjects by name
obj.Open("97/1004") obj = GetRecord("97/1004")
InstantiatingCollections
col = Make<objects> col = Make<objects>
Create new baseobject
obj = New<object> obj = New<object>
Edit object indialog
obj.Edit obj.PropertiesUI
Verify Save OKIf Not obj.Save Then
Msgbox obj.ErrorMessageobj.VerifyIf obj.Verified Then
obj.Save
Record TypeITS_recordType RecordType
Select RecordType
type.Select(hwnd, False) types.SelectAlltype = types.ChooseOneUI
HP TRIM 6 Software Development Kit
Page 415
Select electronicRecord Type
type.Select(hwnd, True) .SelectAll.SetFilter(rfElectronic)type = .ChooseOneUI
Determine viewpane attributes
Use ITS_recordType object.GetNextViewPaneAttribute
Use PropertyDefs object.SelectViewPaneItems
RecordITS_record Record
Create newRecord
rec = NewRecord(recType)rec.SetTitle("A Title")rec.SetNumber("2002/054")rec.Create
rec = NewRecord(recType)rec.Title = ("A Title")rec.LongNumber = "2002/054"rec.Save
Change Type [Not Possible]rec.RecordType = recType
Check-inElectronicDocument
rec.SetDocument(strFile) rec.SetDocumentUI,rec.SetDocument
Uses InputDocument object
Attributes byname
rec.GetAttributerec.SetAttribute
rec.GetPropertyrec.SetProperty
Uses PropertyDef object
User definedfields
15 properties (for example,rec.Field1, rec.Date3)
Multiple definable properties.rec.GetUserFieldrec.SetUserField
Uses FieldDefinition object
Catalogue MailMessages
Use ITS_mailMessage objectrec.CreateFromMailMessage
Use InputDocument objectidoc.SetAsMailMessagerec.SetDocument(idoc)
Relate Recordsrec.SetRelated rec.AttachRelationship
Browse RelatedRecords
Use ITS_search objectsrch.RelatedTo(rec.Uri)
Use RecRelationships objectrels = rec.RecRelationshipsrels.DisplayUI
LocationITS_location Location
Location typeslcName, lcContactlcUnit, lcOrganizationlcPosition
lcPersonlcOrganizationlcPositionlcGrouplcUnknown
Get CurrentUser
loc.Open("%ME%") loc = db.CurrentUser
Create newexternal contactlocations
NewContact NewLocationLocType = lcPersonIsWithin = False
Create new staffwithin a unit
NewStaff(objUnit) NewLocationLocType = lcPersonAddRelationship(objUnit, lrMemberOf)
SearchITS_search RecordSearch
Add Searchsrch.<clause>(for example: srch.TitleWord)
srch.Add<clause>Clause(for example, srch.AddTitleWordClause)
HP TRIM 6 Software Development Kit
Page 416
clause
Sorting Fields specified as strings Fields specified as enum values
Search Criteriadialog
srch.Edit srch.EditQueryUI
Copy searchresults to recordcollection
srch.Fill(recs) recs = srch.GetRecords
Display searchresults
srch.Browse recs = srch.GetRecordsrecs.DisplayUI
Select onerecord fromsearch results
srch.SelectOne recs = srch.GetRecordsrecs.ChooseOneUI
Tag multiplerecords fromsearch results
[Not possible]recs = srch.GetRecordsrecs2 = recs.ChooseManyUI
Access Control rec.AccessControlUses ITS_accessControl
rec.SetAccessControlDetails
HP TRIM 6 Software Development Kit
Page 417
Summary of New Features
New Objects
Action Definition
Thesaurus Keywords
Classification (Record Plan)
Lookup Set & Lookup Item
Electronic Store
Field Definitions
Property Definitions
Census
Litigation Hold
History
HTML Publishing Layouts
Address
Record Locations
Record Relationships
Renditions
Revisions
Requests
Reports
Schedules & Triggers
Space Management
Digital Signatures
Security Levels & Caveats
Zip Codes (Postal Codes)
Workflow
HP TRIM 6 Software Development Kit
Page 418
New Concepts
Verification
Selecting for Collections
Making Reference Files
Property Definitions
Data Strings
Publishing to HTML
Child Lists
Enumeration Helper
Renaming Captions
System/Database Options
HP TRIM 6 Software Development Kit
Page 419
New Features In Detail
Objects
There are vastly more objects in the TRIM 5 and 6 SDK. TRIM Captura's API objectmodel consists of 7 objects, 4 collections and 9 enumeration groups. TRIM 5 and 6,on the other hand, has 43 objects, 39 collections and 62 enumeration groups.
When converting Captura API code to TRIM 5 and 6, all TRIM object declarations willneed to be updated, as the names of all objects represented in the API have changedin TRIM 5 and 6.
The Type Library name in Captura was "tsapi"; in TRIM 5 and 6 it is "TRIMSDK". Youwill only need to use this name as an object qualifier if you have other objectlibraries referenced in your project with similar object names.
TRIM 4.3Public objTRIM As New tsapi.ApplicationPublic objRecord As ITS_recordTRIM 5 and 6Public objTRIM As New TRIMSDK.DatabasePublic objRecord As Record
The equivalent objects and their correct names are tabled below.
Captura (tsapi) CapturaContext (TRIMSDK)
Application Database
ITS_recordType RecordType
ITS_recordTypes RecordTypes
ITS_record Record
ITS_records Records
ITS_search RecordSearch
ITS_searches RecordSearches
ITS_location Location
ITS_locations Locations
ITS_accessControl [none – useRecord.SetAccessControlDetails method]
ITS_mailMessage InputDocument (use SetAsMailMessagemethod)
For new objects, see the Context object model.
HP TRIM 6 Software Development Kit
Page 420
Connecting to TRIM
The TRIM 4.3 API required explicit declaration of a user name, password andDatabase when connecting to TRIM. The programmer's options were to call theConnect method to specify these arguments in code, or to call ConnectTD (orGetLoginDetails then Connect) to get these details from a user in a dialog.
TRIM 5 and 6 manages the connection to the Database through the users' operatingsystem login and the default Database. The Database object's Connect method willattempt to connect the current user to their default Database. It does not requireany parameters.Set objTRIM = New TRIMSDK.DatabaseobjTRIM.Connect
For more details see Connecting.
HP TRIM 6 Software Development Kit
Page 421
Instantiating Objects
Instantiating existing objects in Captura involved calling 'Make<object>' methods onthe Application object to return an object, then passing the URI or Name of therequired object to a Lookup or Open method.
In TRIM 5 and 6, you can instantiate the object at the same time as you create theobject, by passing a name or URI value to a 'Get<object>' method on the Databaseobject. The 'Get…' methods accept a variant parameter for the name or URI of theobject.
'4.3 - Change title of Record number 97/1004Dim objRec As ITS_recordSet objRec = objTRIM.MakeRecord
If Not objRec.Open("97/1004") ThenMsgBox objRec.ErrorMessageExit Sub
End IfobjRec.SetTitle("New Title")objRec.Save
'5.0 - Change title of Record number 97/1004Dim objRec As RecordSet objRec = objTRIM.GetRecord("97/1004")If objRec Is Nothing Then
MsgBox "Record not found"Exit Sub
End IfobjRec.Title = "New Title"objRec.Save
For more details on instantiating objects, see Accessing Persistent Objects.
HP TRIM 6 Software Development Kit
Page 422
Creating an Electronic Record
'4.3'Select the Record TypeSet DocType = app43.MakeRecordTypeIf Not DocType.Select(hwnd, True) Then
MsgBox DocType.ErrorMessage, , "TRIM Image Scanner"Set DocType = NothingExit Sub
End If
'Initialise the new RecordSet detail = app43.NewRecord(DocType) ' Create a new record
'Save/Create the New RecordIf detail.Create(hwnd, TopForm.ctlImgEdit.Image, True) Then
MsgBox "Created. Record Id: " + detail.NumberEnd If
The TRIM 5.0 SDK introduces a new object called an Input Document. It allows theelectronic details of a record to be set up before creating the record. It has twoforms, a file object or a mail message object. Pass the InputDocument object as anargument to the SetDocument method. The properties of the new record can beviewed and edited using the PropertiesUI method of the Record. Call Save to persistthe Record to the Database.
'5.0'Select the Record TypeDim DocTypesCollection As TRIMSDK.RecordTypesDim DocType As TRIMSDK.RecordTypes
Set DocTypesCollection = app50.NewRecordTypes
' Fill the Collection with all Record TypesDocTypesCollection.SelectAll' Filter the Collection, only include those RecordTypes that' support the creation of electronic recordsDocTypesCollection.SetFilter (rfElectronicForCreate)Set DocType = DocTypesCollection.ChooseOneUI(hwnd)
'Initialise the new RecordSet detail = app50.NewRecord(DocType) ' Create a new record
Dim inDoc As New TRIMSDK.InputDocumentinDoc.SetAsFile (TopForm.ctlImgEdit.Image)
'Save/Create the New RecordIf detail.SetDocument(inDoc) Then
detail.PropertiesUI (hwnd)detail.SaveMsgBox "Created. Record Id: " & detail.Number
End If
For more details on creating objects generally, see Creating a New Object.