trimsdk.pdf

HP TRIM

Software Version: 6.2

TRIM SDK

Document Release Date: May 2009

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.

http://h20230.www2.hp.com/selfsolve/manuals


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:


To find more information about access levels, go to:

http://h20230.www2.hp.com/new_access_levels.jsp

http://www.hp.com/go/hpsoftwaresupport


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

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.


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


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.


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


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.


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


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.


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


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


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


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.


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.


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


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


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.


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.


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.


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.


The process for creating a new child object is as follows:


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:


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


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.


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.


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.


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


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


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.


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.


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.


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.


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


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.


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.


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;

}}


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.


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.


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;


Showing and editing the properties of the TRIM Database object

This sample code demonstrates one method of customising the database propertiesin the SDK.



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


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");}


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


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.


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.


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);}


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.


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


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


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.


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;


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


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");


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.


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.


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.


'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


will fail as a result of not setting a mandatory property.


'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");}


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.


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


// 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();


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.


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


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();


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…


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.


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


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


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


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


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


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


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();

}


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


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.


Methods


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


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


Code Examples – C#

Simple Record Search

Adds a TitleWord clause to the Record Search object to find a specifiedindexed Word.


Methods


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);}


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.


Methods


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);}


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);}

}


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.


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


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";


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";


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:


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.

objRecord.SetAccessControlDetails(dxRecordAccess.dxViewRecord,asAccessControlSettings.asPublic,null);

objRecord.SetAccessControlDetails(dxRecordAccess.dxUpdateMetadata,asAccessControlSettings.asInherited,null);

objRecord.SetAccessControlDetails(dxRecordAccess.dxDeleteRecord,asAccessControlSettings.asPrivate, db.GetLocation("Records Manager"));


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.


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


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


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


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


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


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


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();}


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.


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";


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


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.");}


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.


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;


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.



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


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


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.


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");


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


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;


Creating a Record with no user input


' 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


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);}


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.


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;}


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.


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


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");}


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;}


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.



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


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);}


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


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.


CanSaveOrLaunchCurrent

If true, the methods TRIMViewer.SaveCurrent and TRIMViewer.LaunchCurrent willfunction.

If false, these methods will do nothing.

SyntaxTRIMviewer.CanSaveOrLaunchCurrent = [Boolean]


DocFormat (Read Only)

The format of the document known to the viewer via the View method.

Syntax[vwDocFormat ] = TRIMviewer.DocFormat


Enabled

Returns/sets a value that determines whether an object can respond to user-generated events.

SyntaxTRIMviewer.Enabled = [Boolean]


Font

Font used by the control.

SyntaxTRIMviewer.Font = [stdole.IfontDisp ]


MenuHandle (Read Only)

HMenu Handle to a menu, usually a Right Mouse Button menu

Syntax[Boolean] = TRIMviewer.MenuHandle


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]


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


Text

Returns/Sets a string that is displayed in the TRIMviewer control when there is nofile currently being displayed.

SyntaxTRIMviewer.Text = [String]


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


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


Copy

Copy Selection to the Clipboard.

SyntaxTRIMviewer.Copy ()


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


DoMenu

Do not use.


EnableMenu

Do not use.


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


Print

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


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.


PrintCurrent

Prints the file that is currently being viewed, showing a print dialog if desired.

SyntaxTRIMviewer.PrintCurrent (showDialogs As Boolean)

Parameters


showDialogs Boolean Indicates if a print dialog (user interface) is tobe displayed prior to printing. Set this value totrue to display the dialog.


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


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


Events

Name Description

ViewOccurs when an object inside the file being viewed isdouble clicked


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


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.


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


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.


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


Constituent Controls

Name Picture

Spell Check

File OpenControl


Save AsControl

CalendarControl


Browse FolderControl

As you can see the TRIMedit control can be a powerful tool to get requiredfunctionality into your program fast.


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


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


Verification


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


Fonts


Type

All fields on the Fontspage

FontifontDisp

The fonts page is provided to assist the programmer in setting the attributes of thefont property.


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


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


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


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]


AllowBlankTime

Allow the Time section of the control when in Date and Time mode to be blank.

SyntaxTRIMedit.AllowBlankTime = [Boolean]


AllowCreate

Enables the control to create a file system directory or folder when required.

SyntaxTRIMedit.AllowCreate = [Boolean]


AllowOverwrite

Enables the control to overwrite an existing file where required.

SyntaxTRIMedit.AllowOverwrite= [Boolean]


Border

Detirmines if the control will be displayed with a boarder (3D) or without (flat).

SyntaxTRIMedit.Border= [Boolean]


BrowseState

Returns/Sets the active state of the control.

SyntaxTRIMedit.BrowseState= [ksBrowseMode]


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]


CanUndo

Determines if the EditUndo method is able to be used.

SyntaxTRIMedit.CanUndo= [Boolean]


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]


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]


CurSel

Returns/Sets the index of the item selected on the dropdown list,

SyntaxTRIMedit.CurSel= [Long ]


CursorPosition

Returns/Sets the current position of the cursor in the text area of the control.

SyntaxTRIMedit.CursorPosition= [Long]


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]


Enabled

Returns/sets a value that determines whether an object can respond to user-generated events.

SyntaxTRIMedit.Enabled= [Boolean]


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]


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]


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.


Font

Returns/Sets the font used in the text area of the control.

SyntaxTRIMedit.Font = [stdole.IFontDisp]


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.


HistoryCount (Read Only)

Returns/Sets the count of the number of history items.

SyntaxTRIMedit.HistoryCount = [Long]


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


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]


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 ]


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]


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]


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]


MaxLength

Returns/Sets the maximum characters that the user is allowed to enter in the textarea of the control.

SyntaxTRIMedit.MaxLength= [Long ]


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.


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]


Name (ReadOnly)

Returns the name used in code to identify this control. The name property can onlybe set at design time.

SyntaxTRIMedit.Name= [String ]


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]


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]


ScrollBars

Returns/Sets a value that determines which if any, scroll bars are displayed on thecontrol.

SyntaxTRIMedit.ScrollBars= [ksScrollMode]


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.


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]


TabIndex

Returns/sets the tab order of an object within its parent form.

SyntaxTRIMedit.TabIndex= [Integer]


TabStop

Returns/sets a value indicating whether a user can use the TAB key to give the focusto this control.

SyntaxTRIMedit.TabStop= [Boolean]


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]


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


ToolTips

Returns/Sets a value that determines if extra text will be displayed for this control asa tooltip.

SyntaxTRIMedit.ToolTips = [Boolean]


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.


Validated

Returns/Sets a value that determines the validation state of the control.

SyntaxTRIMedit.Validated= [ksEditValidMode]


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]


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


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


AddHistory

Adds the nominated text as a history item for the control.

SyntaxTRIMedit.AddHistory (Text As String)

Parameters


Text String The string to be added as a history item


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



Index Long The index at which to add the historyitem


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



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)


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



Uri Variant The unique record identifier of the object thishistory item represents (for example, TRIM RecordUri)



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


Text String The string to be added as an item to thedropdown list


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


Text String The string to be added as an item to thedropdown list

Index Long The index at which to add the item


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



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)


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



Uri Variant The unique record identifier of the object thisdropdown item represents (for example, TRIMRecord Uri)



EditCopy

Copy the value of any selected text to the clipboard.

SyntaxTRIMedit.EditCopy ()


EditCut

Copies the value of the selected text to the clipboard and sets the value of theselected text to a null string.

SyntaxTRIMedit.EditCut ()


EditDelete

Sets the value of the selected text to a null string.

SyntaxTRIMedit.EditDelete ()


EditPaste

Sets the value of the selected text to a the string held in the clipboard, updating thetext area of the control.

SyntaxTRIMedit.EditPaste ()


EditUndo

Undoes the last command performed in the text area. Depends on the CanUndoproperty being set to True.

SyntaxTRIMedit.EditUndo ()


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


Text String The string to find in the dropdown list

Return Value

Type Description

Long Returns index of the item in the list


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


Uri Variant The Uri to look for in the list items

Return Value

Type Description

Long Returns index of the item in the list


GetListAt

Returns the value in the dropdown list at the specified index.

Syntax[String] =TRIMedit.GetListAt (index as Long)

Parameters


index Long Index of the list item you want returned

Return Value

Type Description

String Value of the text in the dropdown list


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


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


GetUriAt

Returns the Uri of the nominated dropdown list item.

Syntax

[Variant] =TRIMedit.GetUriAt (index As Long)

Parameters


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


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


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


RemoveHistory

Removes the history item at the specified index.

Syntax[Boolean] = TRIMedit.RemoveHistory (index As Long)

Parameters


Index Long Index of the history item to remove

Return Value

Type Description

Boolean Returns true on success


RemoveItem

Removes the specified item from the dropdown list.

Syntax[Boolean] =TRIMedit.RemoveItem (index As Long)

Parameters


index Long Index of the dropdown item to remove

Return Value

Type Description



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


ReplaceStr String The string that will replace thecurrent selection

CanUndo Boolean Enables the undo of this Action


ResetHistory

Clears the history for this control. It is the same as doing a RemoveHistory on eachof the history items.

SyntaxTRIMedit.ResetHistory ()


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


SaveHistory

Saves the control's current history items to the registry at the key specified in theHistoryKey property.

SyntaxTRIMedit.SaveHistory ()


SetIcons

Internal use only.

Syntax[Boolean] =TRIMedit.SetIcons (smallIcon, bigIcon)

Parameters


smallIcon For internal use only

bigIcon For internal use only

Return Value

Type Description

Boolean For internal use only


SetSel

Selects text using the start and end positions specified.

Syntax[Boolean] =TRIMedit.SetSel (startChar As Long, endChar As Long)

Parameters


startChar Long Start selection position

endChar Long End Selection Position


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


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


SpellCheck

Runs the TRIM spelling checker against the contents of the text area.

Syntax

TRIMedit.SpellCheck ()


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


displayError Boolean If an error occurs during this method thisparameter indicates if they are to bedisplayed

forceVerify Boolean ***UNDER CONSTRUCTION***

Return Value

Type Description



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


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


Reserved Boolean Reserved for future use


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


Change

Similar to the Change event on a Visual Basic Textbox, the event occurs when thecontents of the text area is changed.

SyntaxTRIMedit_Change ()


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


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


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


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


HistorySelected

Occurs if an item on the dropdown list has been selected by the user.

SyntaxTRIMedit_HistorySelected ()


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


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


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


SelChange

Occurs if a different item on the dropdownlist has been selected.

SyntaxTRIMedit_SelChange ()


ValidChanged

Occurs if the value of the controls Validated property has changed.

SyntaxTRIMedit_ValidChanged ()


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


DisplayError Boolean Determines if a dialog is to bedisplayed with any error information

NewValidState ksEditValidMode The valid state of the control


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.


Sample Code

TRIMtreeBox – list TRIM records example (Visual Basic)

TRIMtreeBox – list TRIM records example (C#)

TRIMtreeBox – Bouncing list example (Visual Basic)


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


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


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)


'// 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


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.


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


Objects


TRIMSDK.Database



TRIMSDK.Records

TRIMSDK.Record

Methods

TRIMtreeBox

AddManyColumns

AddManyRows

GetFirstRow

GetNextRow


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


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();


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


// 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";}

}


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.


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:


Objects


TRIMSDK.Database



TRIMSDK.Records

TRIMSDK.Record

Methods

TRIMtreeBox

AddManyColumns

AddManyRows

Database

NewRecordSearch


MakeRecords

GetRecord

PropertyDefs

SelectTreeColumns

RecordSearch

ChooseManyUI

SelectContentsOf

GetTreeString

Properties

TRIMtreeBox

Message

Full

Record

IsContainer

Events

TRIMtreeBox

AboutToExpand

RoomForRows


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


'/// 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


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


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


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


AllowExpandAll

Returns/Sets a value that determines if rows in the treebox can be expanded in arecursive fashion.

SyntaxTRIMtreeBox.AllowExpandAll = [Boolean]


AllowSort

Returns/Sets a value that determines if rows in the treebox can be sorted based inthe values in a column.

SyntaxTRIMtreeBox.AllowSort = [Boolean]


AnyTagged (Read Only)

Returns a value that indicates if any rows in the treebox have been tagged.

Syntax[Boolean] = TRIMtreeBox.AnyTagged


ColumnCount (Read Only)

Returns a value that indicates the number of columns currently in the treebox.

Syntax[Long] = TRIMtreeBox.ColumnCount


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


Count (Read Only)

Returns a value that indicates the number of rows in the treebox.

Syntax[Long] = TRIMtreeBox.Count


CurrentRow (Read Only)

Returns the current selected row in the treebox.

Syntax[TRIMtreeRow] = TRIMtreeBox.CurrentRow


CurSel

Returns the index of the currently selected row or sets the current selected row bythe index.

SyntaxTRIMtreeBox.CurSel = [Long]


DbId

For Internal use only.


Font

Returns/Sets the font used to display text in the treebox.

SyntaxTRIMtreeBox. Font = [stdole.IFontDisp]


Full

Returns/Sets a value that indicates if the treebox has loaded all of the availablerows.

SyntaxTRIMtreeBox. Full = [Boolean]


Heading

Returns/Sets a value that determines if the column heading is used.

SyntaxTRIMtreeBox.ColumnCount = [Boolean]


IdealHeight (Read Only)

Returns a value that indicates


Syntax[Long] = TRIMtreeBox.Count


IdealWidth (Read Only)

Returns a value that if used, as the controls width will display all visible columns inthe treebox.

Syntax[TRIMtreeRow] = TRIMtreeBox.CurrentRow


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]


NumberTagged (Read Only)

Returns a value that is the number of tagged rows.

Syntax[Long] = TRIMtreeBox.NumberTagged


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:


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


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


ScrollBars

Returns/Sets a value that determines if and which ScrollBars will be used by thetreebox control.

SyntaxTRIMtreeBox.ScrollBars= [ksScrollMode]


SelectFirstRow

Returns/Sets a value that determines if the first row in the treebox will be selectedby default.

SyntaxTRIMtreeBox.SelectFirstRow= [Boolean]


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]


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]


TaggingMode

Returns/Sets a value that determines if tagging is allowed.

SyntaxTRIMtreeBox.TaggingMode = [tbTagMode]


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]


ToolTips

Returns/Sets a value that determines if tooltips will be active or not.

SyntaxTRIMtreeBox.ToolTips = [Boolean]


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


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


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


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


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


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


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


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


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


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


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



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


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


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


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


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


ClearColumns

Clears the the TRIMtreeBox control. Columns and as a result any existing rows getcleared by this method.

SyntaxTRIMtreeBox.ClearColumns ()


ClearList

Clears any rows from the control. Columns are left intact by this method.

SyntaxTRIMtreeBox. ClearList ()


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


Index Long The index of the row in the TRIMtreeBox thatis to be to acted upon


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


DeleteColumn

Removes a column from the TRIMtreeBox.


SyntaxTRIMtreeBox.DeleteColumn (Column)

Parameters


Column Variant Accepts either the column index OR a TRIMtreeCol


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


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


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


Index Long Index of the row in the TRIMtreeBox to beexpanded

recursive Boolean Switch that determines if child rows are to beexpanded also


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


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


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


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


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


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


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


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


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


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


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.


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


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


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


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


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


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


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


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.


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.


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


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


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


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.


TagAll

Tag or untag all rows in the TRIMtreeBox control depending on the specified taggedstate.

SyntaxTRIMtreeBox.TagAll (NewTagState As Boolean)

Parameters


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.


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


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


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.


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


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.


BreakTriggered

Occurs if the user pressed the 'Break' key whilst doing a sort.

SyntaxTRIMtreeBox_ BreakTriggered ()


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


Col TRIMtreeCol The column about to be made visable

CellNumber Long The cell number of the column


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


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.


DelKeyPressed

Occurs if the Delete (Del) key is pressed while a row is selected and the control hasfocus.

SyntaxTRIMtreeBox_DelKeyPressed (Row As TRIMtreeRow)

Parameters


Row TRIMtreeRow The selected row

Remarks

This event can be used call code to remove the selected row if appropriate.


FileDropped

Occurs if a or some files have been dropped onto a row in the control.


SyntaxTRIMtreeBox_FileDropped (OverRow As TRIMtreeRow, FileList As String, FileCount As Long)

Parameters


Row TRIMtreeRow The selected row


LButtonClick

Occurs if the left mouse button is clicked while on a row in the control.

SyntaxTRIMtreeBox_LButtonClick (Row As TRIMtreeRow)

Parameters


Row TRIMtreeRow The row on which the left click occured


LButtonDblClick

Occurs if the left mouse button is double clicked while on a row in the control.

SyntaxTRIMtreeBox_LButtonDblClick (Row As TRIMtreeRow)

Parameters


Row TRIMtreeRow The row on which the left click occured


MenuItemEnable

For Internal Use Only.

SyntaxTRIMtreeBox_MenuItemEnable (Id As Long, Handled As Boolean, ShouldEnable As Boolean)

Parameters


Id Long Reserved

Handled Boolean Reserved

ShouldEnable Boolean Reserved

Remarks

This event is reserved for internal use.


MenuItemSelected


SyntaxTRIMtreeBox_MenuItemSelected (Id As Long, Handled As Boolean)

Parameters


Id Long Reserved

Handled Boolean Reserved

ShouldEnable Boolean Reserved

Remarks



OLEDragDrop


SyntaxTRIMtreeBox_OLEDragDrop (OverRow As TRIMtreeRow, SrcUri, SrcType As Long, Effect As Long,State As Long, X As Long, Y As Long)

Parameters


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.


OLEDragOver


SyntaxTRIMtreeBox_OLEDragOver (OverRow As TRIMtreeRow, SrcUri, SrcType As Long, Effect As Long,State As Long, X As Long, Y As Long)

Parameters


OverRow TRIMtreeRow Reserved

SrcUri Variant Reserved

SrcType Long Reserved


State Long Reserved

X Long Reserved

Y Long Reserved

Remarks



OLEStartDrag


SyntaxTRIMtreeBox_OLEStartDrag (DragRow As TRIMtreeRow, Effect As Long)

Parameters


DragRow TRIMtreeRow Reserved


Remarks



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


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.


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


PrefixCol TRIMtreeCol The column on which the reselected prefixsearch is being carried out

Prefix String The new prefix to search by


RButtonClick

Occurs if the right mouse button is clicked while on a row in the control.

SyntaxTRIMtreeBox_RButtonClick (Row As TRIMtreeRow)

Parameters


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


RButtonDblClick

Occurs if the right mouse button is double clicked while on a row in the control.

SyntaxTRIMtreeBox_ RButtonDblClick (Row As TRIMtreeRow)

Parameters


Row TRIMtreeRow The row on which the left click occurred


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


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.


SelectionChanged

Occurs if a different row is selected.

SyntaxTRIMtreeBox_SelectionChanged ()


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


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.


TagChanged

Occurs if the tagged state of a row is changed.

SyntaxTRIMtreeBox_TagChanged (Row As TRIMtreeRow)

Parameters


Row TRIMtreeRow The row whose tagged state has changed


TimerTriggered


SyntaxTRIMtreeBox_TimerTriggered (Id as Long)

Parameters


Id Long Reserved.

Remarks



TopSelChanged

Occurs if the visible top row changes, usually caused by the user scrolling up ordown in the TRIMtreeBox control.

SyntaxTRIMtreeBox_TopSelChanged ()


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


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.


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


CannedDate

Returns/Sets the canned date value of the TRIMdateTime.

SyntaxTRIMdateTime.CannedDate= [dtCannedDate]


Date

Returns/Sets the date value of the TRIMdateTime.

SyntaxTRIMdateTime.Date = [Date]


DateHi

Returns/Sets.


SyntaxTRIMdateTime.DateHi = [Date]


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 ]


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]


TRIMfavorites

Reserved. This object class is not currently in use.


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.


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


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]


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]


CharWidth

Returns/Sets the width of the column in characters.

SyntaxTRIMtreeCol.CharWidth = [Long]


DisplayMode

Returns/Sets a value that determines if the column will display Icons, Text or both.

SyntaxTRIMtreeCol.DisplayMode = [tbDisplayMode]


Ellipsis

Returns/Sets a value that determines if ellipsis (…) will be displayed if the text in acolumn does not all fit.

SyntaxTRIMtreeCol.Ellipsis = [tbEllipsisMode]


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]


Index (Read Only)

Returns a value that is the current index for the column.

Syntax[Long] = TRIMtreeCol. Index


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]


Sizeable

Returns/Sets a value that determines if the columns width can be customized atruntime.

SyntaxTRIMtreeCol.Alignment = [tbAlignmentMode]


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]


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]


Visible

Returns/Sets a value that determines if the column is displayed.

SyntaxTRIMtreeCol.Visible = [Boolean]


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]


Width (Read Only)

Returns a value that is the columns width in pixels.

SyntaxTRIMtreeCol.Width = [Long]


Methods

Name ``

SetIcon Sets the icon to use in this column


SetIcon

Sets the Icon to be used in this column.

Syntax[Boolean] = TRIMtreeCol. SetIcon (Icon)

Parameters


Icon Variant ***UNDER CONSTRUCTION***

Return Value

Type Description

Boolean Returns the success of the method


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.


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


AutoRedraw

Returns/Sets a value that determines if auto redrewar is enabled.

SyntaxTRIMtreeRow.AutoRedraw = [Boolean]


Bold

Returns/Sets a value that determines if the font appears bold in the row.

SyntaxTRIMtreeRow.Bold = [Boolean]


Enabled

Returns/Sets a value that determines if the row is enabled.

SyntaxTRIMtreeRow.Enabled = [Boolean]


EverExpanded (Read Only)

Returns a value that indicates if the row has ever been expanded.

SyntaxTRIMtreeRow.EverExpanded = [Boolean]


Expanded (Read Only)

Returns a value that indicates if the row is currently expanded.

SyntaxTRIMtreeRow.Expanded = [Boolean]


ExpandLocked

Returns/Sets a value that determines if the row can be expanded or collapsed.

SyntaxTRIMtreeRow. ExpandLocked = [Boolean]


Id

Returns/Sets an identifier value on the row. For TRIM objects this could indicate theobject type (btyBaseObjectTypes).

SyntaxTRIMtreeRow.Id = [Long]


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]


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]


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]


Tagged

Returns/Sets the tagged state of the row.

SyntaxTRIMtreeRow.Tagged = [Boolean]


TagStateLocked

Returns/Sets a boolean that determines if a user can tag or untag a row through theuser interface.

SyntaxTRIMtreeRow.TagStateLocked = [Boolean]


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]


Visible

Returns/Sets the visible state of the row.

SyntaxTRIMtreeRow.Visible = [Boolean]


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


AddChild

Adds a child row to this TRIMtreeRow.

Syntax[TRIMtreeRow] = TRIMtreeRow.AddChild (Text As String, Uri, MayHaveKids As Boolean, Id AsLong)

Parameters


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


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



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.


ClearChildren

Removes any child rows from the TRIMtreeRow.

SyntaxTRIMtreeRow.ClearChildren ()


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


DeleteChildRow

Removes the child row at the specified index from the TRIMtreeBox control.

SyntaxTRIMtreeRow. DeleteChildRow (Index as Long)

Parameters


Index Long The index of the child row to remove


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


recursive Boolean Determines if the ExpandRow function should beapplied to any child rows that may have child rowsin turn (MayHaveKids = true)


GetCellText

Returns the value as a string of the specified cell from this TRIMtreeRow in theTRIMtreeBox control.

Syntax[String] = TRIMtreeRow.GetCellText (Column)

Parameters


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


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


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


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.


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.


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


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


SetCellIcon

Sets the Icon used in the specified cell of this TRIMtreeRow.

Syntax[Boolean] = TRIMtreeRow.SetCellIcon (Column, Icon)

Parameters


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



SetCellText

Sets the text used in the specified cell of this TRIMtreeRow.

Syntax[Boolean] = TRIMtreeRow. SetCellText (Column, Text as String)

Parameters


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



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


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


fvFavoriteType


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)


ksBrowseMode


ksBrowseDisabled 0 Disabled

ksBrowseActive 1 Active

ksBrowseEvenLocked 2 Browse active even when locked


ksCannedDatesMode


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


ksEditValidMode


ksUnknown -1 Unknown

ksNotValidated 0 Invalid

ksValid 1 Valid

ksAmbiguous 2 Ambiguous


ksScrollMode


ksNone 0 No Scroll bars

ksHoriz 1 Horizontal scroll bar

ksVert 2 Vertical scroll bar

ksBoth 3 Both horizontal and vertical scroll bars


ksSelectMode


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)


tbAlignmentMode


tbaLeft 0 Align Left

tbaRight 1 Align Right

tbaCenter 2 Align Centre


tbDisplayMode


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


tbEllipsisMode


tbeNone 0 No ellipsis

tbeRight1

Ellipsis displayed to the right of the text when itdoes not fit in the display area


ltbSortMode


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


tbSortState


tbssUnsorted 0 Unsorted

tbssAscending 1 Sort Ascending

tbssDescending 2 Sort Descending


tbTagMode


tbtmDisabled 0 Tagging disabled

tbtmTags 1 Tagging enabled


tbVisibleMode


tbvEither0

Can be hidden or visable (usersdescretion)

tbvHidden 1 Must be hidden

tbvMandatory 2 Must be visable


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


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


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


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


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


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


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


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


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


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


vwDocFormat


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


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.

http://support.openview.hp.com/


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


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)


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


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


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


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.


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.


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.


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.

trimsdk.pdf

Documents

hp software online support

hp software support

hp products

software release date

hp support contacts

support contracts

hp trimsoftware version

commercial computer