IDL iTool Programming User Manual

iTool Programming

IDL Version 7.0 November 2007 Edition

1107IDL70ITD

Restricted Rights Notice

The IDL®, IDL Analyst™, ENVI®, and ENVI Zoom™ software pro grams and the accompanying proced ure s , fun ct io ns, and documentation described herein are sold under license agreement. Their use, duplication, and disclosure are subject to the restrictions stated in the license agreement. ITT Visual Information Solutions reserves the right to make changes to this document at any time and without noti ce .

Limitation of Warranty

ITT Visual Information Solutio ns makes no war r anties, eith er express or implied, as to any matter not expressly set forth in the license agreement, inclu d in g w ithout limitation the condition of the so ft ware, me rc hantability, or fitness for any particular purpose.

ITT Visual Information Solutions shall not be liable for a ny dire ct , c onse que ntial, or other damages suffered by the Licensee o r any others resulting from use of the software pac kages or their documentation.

Permission to Reproduce this Manual

If you are a licensed user of these products, ITT Visual Information Solutions grants you a limit ed, nontransferable license to reproduce this particular document provided such copies are for your use only and are not sold or distributed to third parties. All suc h copies must contain the ti tl e page and this notice page in th eir entirety.

Export Control Information

This software and its associated documentation are subject to t he c ontrols of the Export Administra ti on Regulations (EAR). It has been determined that this software is cl assi fied as E AR99 under U.S. Export Control laws and regulat i ons, and may not be retransferred to any destination expressly prohibited by U.S. laws and regulations. The recipient is responsible for ensuring compliance to all applicable U.S. Export Control laws and regulations.

Acknowledgments

ENVI® and IDL® are registered trademarks of ITT Corporation, registered in the United States Patent and Tradem ar k Of fice. ION™, ION Script™, ION Java

™, and ENVI Zoom™ are trademarks of ITT Visual Information Solutions.

Numerical Recipes™ is a trademark of Numerical Recipes Software. Numerical Recipes routines are used by permission. GRG2™ is a trademark of Windward Technologies, Inc. The GRG2 software for nonlinea r optimiz ation is used by permission. NCSA Hierarchical Data Format (HDF) Software Library and Utilities. Copyright © 1988-2001, The Board of Trustees of the University of Illinois. All

Illinois. All rights reserved. CDF Library. Copyright © 2002, National Space Science Data Center, NASA/Goddard Space Flight Center. NetCDF Library. Copyright © 1993-1999, University Corporation for Atmospheric Research/Unidata. HDF EOS Library. Copyright © 1996, Hughes and Applied Research Corporation. SMACC. Copyright © 2000-2004, Spectral Sciences, Inc. and ITT Visual Information Solutions. All rights reserved. This software is based in part on the work of the Independent JPEG Group. Portions of this software are copyrighted by DataDirect Technologies, © 1991-2003.

2001. The University of New South Wales, UNSW, Sydney NSW 2052, Australia, and Unisearch Ltd, Australia. This product includes software developed by the Apache Software Foundation (www.apache.org/). MODTRAN is licensed from the United States of America under U.S. Patent No. 5,315,513 and U.S. Patent No. 5,884,226. FLAASH is licensed from Spectral Sciences , Inc. under a U.S. Patent Pen ding. Portions of this software are copyrighted by Merge Technologies Incorporated. Support Vector Machine (SVM) is based on the LIBSVM library written by Chih-Chung Chang and Chih-Jen Lin (www.csie.ntu.edu.tw/~cjlin/libsvm),

adapted by ITT Visual Information Solutions for remote sensing image supervised classification purposes. IDL Wavelet Toolkit Copyright © 2002, Christopher Torrence. IMSL is a trademark of Visual Numerics, Inc. Copyright © 1970-2006 by Visual Numerics, Inc. All Rights Reserved. Other trademarks and registered trademarks are the property of the respective trademark holders.

Contents

Chapter 1

Overview of iTools ................................................................................... 9

What are iTools? ............................................................................................................. 10

What is the iTools Component Framework? ................................................................... 11

About this Manual ........................................................................................................... 12

About the iTools Code Base ............................................................................................ 13

Skills Required to Use the iTools Component Framework ............................................. 15

Part I: Understanding the iTools Component Framework

Chapter 2

iTool System Architecture .................................................................... 19

Overview of the iTool System Architecture .................................................................... 20

iTools Object Model Diagram ......................................................................................... 21

iTool Objec t Identifiers ................................................................................................... 28

iTool Object Hierarchy .................................................................................................... 31

iTool Developer’s Guide 3

Registering Components .................................................................................................. 38

iTool Messaging System .................................................................................................. 41

System Resources ............................................................................................................ 44

Chapter 3

Data Management ................................................................................. 51

Overview of iTool Data Management ............................................................................. 52

iTool Data Manager ......................................................................................................... 53

iTool Data Types .............................................................................................................. 54

iTool Data Objects ........................................................................................................... 56

Predefined iTool Data Classes ......................................................................................... 58

Parameters ........................................................................................................................ 61

Data Type Matching ........................................................................................................ 63

Data Update Me chanism .................................................................................................. 65

Chapter 4

Property Management .......................................................................... 67

About the Properties Interface ......................................................................................... 68

Property Data Types ........................................................................................................ 71

Registering Properties ...................................................................................................... 74

Property Identifiers .......................................................................................................... 77

Property Attributes ........................................................................................................... 78

Property Aggregation ....................................................................................................... 81

Property Update Mechanism ............................................................................................ 84

Properties of the iTools System ....................................................................................... 85

Part II: Using the iTools Component Framework

Chapter 5

Creating an iTool ................................................................................... 89

Overview of iTool Creation ............................................................................................. 90

Creating a New iTool Class ............................................................................................. 91

Registering a New Tool Class ........................................................................................ 101

Creating an iTool Launch Routine ................................................................................. 103

Example: Simple iTool .................................................................................................. 108

Contents iTool Developer’s Guide

Chapter 6

Creating a Visualization ...................................................................... 113

Overview of iTool Visualization Types ........................................................................ 114

Predefine d iTool Visualization Cla sses ......................................................................... 115

Creating a New Visualization Type .............................................................................. 121

Registering a Visualization Type .................................................................................. 136

Unregistering a Visualization Type ............................................................................... 138

Example: Image-Contour Visualization ........................................................................ 140

Chapter 7

Creating an Operation ........................................................................ 145

Overview of Creating an iTool Operation ..................................................................... 146

Predefined iTool Operations ......................................................................................... 148

Operations and the Undo/Redo System ......................................................................... 150

Creating a New Data-Centric Operation ....................................................................... 152

Creating a New Generalized Operation ......................................................................... 165

Operations and Macros .................................................................................................. 181

Registerin g an Operati on ............................................................................................... 182

Unregistering an Operation ........................................................................................... 184

Example: Data Resample Operation ............................................................................. 186

Chapter 8

Creating a Manipulator ....................................................................... 193

Overview of iTool Manipulators ................................................................................... 194

The Manipulator Creation Process ................................................................................ 197

Predefined iTool Manipulators ...................................................................................... 198

Manipulators and the Undo/Redo System ..................................................................... 202

Using Manipulator Public Instance Data ....................................................................... 204

Creating a New Manipulator ......................................................................................... 206

Registering a Manipulator ............................................................................................. 223

Unregistering a Manipulator ......................................................................................... 225

Example: Color Table Manipulator ............................................................................... 226

Chapter 9

Creating a File Reader ........................................................................ 229

Overview of iTool File Readers .................................................................................... 230

Predefined iTool File Readers ....................................................................................... 231

iTool Developer’s Guide Contents

Creating a New File Reader ........................................................................................... 234

Registering a File Reader ............................................................................................... 245

Unregistering a File Reader ........................................................................................... 246

Example: TIFF File Reader ........................................................................................... 248

Chapter 10

Creating a File Writer ......................................................................... 253

Overview of iTool File Writers ...................................................................................... 254

Predefined iTool File Writers ........................................................................................ 255

Creating a New File Writer ............................................................................................ 258

Registering a File Writer ................................................................................................ 269

Unregistering a File Writer ............................................................................................ 270

Example: TIFF File Writer ............................................................................................ 272

Part III: Modifying the iTool User Interface

Chapter 11

iTool User Interface Arc hit ect ure ...................................................... 279

Overview of iTool Interface Architecture ...................................................................... 280

User Interface Objects .................................................................................................... 282

Chapter 12

Using iTool User Interface Elements ................................................ 285

The iTools Feedback Mechanism .................................................................................. 286

Status Messages ............................................................................................................. 287

Prompts .......................................................................................................................... 289

Informational Messages ................................................................................................. 291

Chapter 13

Creating a User Interface Service ..................................................... 293

Overview of the iTool UI S ervice .................................................................................. 294

Predefined iTool UI Services ......................................................................................... 295

Creating a New UI Service ............................................................................................ 297

Registering a UI Service ................................................................................................ 302

Executing a User Interface Service ................................................................................ 304

Example: Changing a Property Value ............................................................................ 305

Contents iTool Developer’s Guide

Chapter 14

Creating a User Interface Panel ......................................................... 311

Overview of the iTool UI Panel .................................................................................... 312

Creating a UI Panel Interface ........................................................................................ 313

Creating Callback Routines ........................................................................................... 318

Registering a UI Panel ................................................................................................... 320

Example: A Simple UI Panel ........................................................................................ 322

Chapter 15

Creating a Custom iTool Widget Interface ........................................ 331

About Custom iTool Widget Interfaces ........................................................................ 332

Overview of Creating an iTool Interface ...................................................................... 335

iTool Widget Interface Concepts .................................................................................. 338

Creating the Interface Routine ...................................................................................... 340

Adding Menus ............................................................................................................... 344

Adding a Toolbar ........................................................................................................... 346

Adding an iTool Window .............................................................................................. 348

Adding a Status Bar ....................................................................................................... 350

Adding a User Interface Panel ....................................................................................... 351

Handling Callbacks ....................................................................................................... 352

Handling Resize Events ................................................................................................. 354

Handling Shutdown Events ........................................................................................... 356

Creating an iTool Launch Routine ................................................................................ 358

Example: a Custom iTool Interface ............................................................................... 360

Appendix A

Controlling iTools from the IDL Command Line ............................... 379

Overview of iTool Prog rammatic Control .................................................................... 380

Retrievin g an iTool Obje ct Reference ........................................................................... 381

Retrieving Component Identifiers ................................................................................. 382

Retrieving Property Information ................................................................................... 385

Changing Property Values ............................................................................................. 389

Running Operations ....................................................................................................... 391

Selecting Items in the iToo l ........................................................................................... 393

Replacing Data in an iTool ............................................................................................ 394

iTool Developer’s Guide Contents

Appendix B

iTool Compound Widgets .................................................................. 397

Overview of iTools Compound Widgets ....................................................................... 398

CW_ITMENU ................................................................................................................ 399

CW_ITPANEL .............................................................................................................. 404

CW_ITSTATUSBAR .................................................................................................... 408

CW_ITTOOLBAR ........................................................................................................ 411

CW_ITWINDOW .......................................................................................................... 416

Index .................................................................................................... 419

Contents iTool Developer’s Guide

Chapter 1

Overview of iTools

This chapter provides an overview of the IDL iTool Component Framework.

What are iTools? . . . . . . . . . . . . . . . . . . . . . 10

What is the iTools Component Framework? 11

About this Manual . . . . . . . . . . . . . . . . . . . . 12

iTool Developer’s Guide 9

About the iTools Code Base . . . . . . . . . . . . 13

Skills Required to Use the iTools Component

Framework . . . . . . . . . . . . . . . . . . . . . . . . . 15

10 Chapter 1: Overview of iTools

What are iTools?

IDL Intelligent Tools, or iTools, are applications written in IDL to perform a variety of data analysis and visualization tasks. iTools share a common underlying application frame work, prese nting a full-fe atured, customiz able, applicatio n-like user interface with menus, toolbars, and other graphical features. Several predefined iTools are provided along with IDL; you can use these tools to explore and visualize your data without writing any new code yourself. For information on using the standard iTools provided with IDL, see the iTool User’s Guide.

But iTools are more than just a set of pre-written IDL programs. Behind the iTool system lies the IDL Intelligent Tools Component Framework — a set of object class files and associated utilities designed to allow you to easily extend the supplied toolset or create entirely new tools of your own. This manual will help you understand the iTools Component Framework so that you can customize existing iTools or create entirely new ones.

What are iTools? iTool Developer’s Guide

Chapter 1: Overview of iTools 11

What is the iTools Component Framework?

The iTools component framework is a set of object class definitions written in the IDL language. It is designed to facilitate the development of sophisticated visualization tools by providing a set of pre-built components that provide standard features including:

• creation of visualization graphics

• mouse manipulations of visualization graphics

• annotations

• management of visualization and application properties

• undo/redo capabilities

• data imp ort and export

• printing

• data filtering and manipulation

• interface element event handling

In addition, the iTools component framework makes it easy to e xtend the syst em with components of your own creation, allowing you to design a tool to manipulate and display your data in any way you choose.

Advantages of Using the Framework

If you are accustomed to cre ating user interf aces for yo ur IDL applic ations usi ng IDL widgets, using the iTools component framework will shorten your development time by providing much of the application interface via the standard component building blocks. In many cases, you are freed entirely from the need to create your own interface element s, handl e widget e v ents, an d manage the dis play of da ta. Ev en when your application calls for additional user interface elements, the framework eliminates the need for you to manually create those elements that your application has in common with the stan dard iTool interface.

If you are accustomed to using IDL object graphics in your applications, the iTools component framework provides a streamlined way of working with the object graphics hierarchy. Many tasks, such as management of object properties and manipulation of the object model, are handled automatically.

iTool Developer’s Guide What is the iTools Component Framework?

12 Chapter 1: Overview of iTools

About this Manual

The iTool Developer’s Guide describes the IDL iTools component framework and provides examples of its use. After reading this manual, you will understand how to use the component framework to create your own intelligent tools.

This manual is divided into three parts:

Part I: Understanding the iTools Component Framework

This section describes the iTools component framework in conceptual terms, and outlines some of the processes you will use in creating new tools using the framework. While an understanding of the topics in this section may be beneficial as you develop your own applications, a complete understanding of the way the framework operates is not required to begin building your own tools.

Part II: Using the iTools Component Framework

This section walks you through the pr ocess of cre ating a ne w iTool application, either by extending an existing iTool or by building a new tool from scratch.

Part III: Modifying the iTool User Interface

This section discusses the process of adding your own interface elements to an iTool application.

What this Manual is Not

This manual is not an API reference for the iTools object classes. Reference documentation for the iTool classes, methods, and properties is located in the IDL Reference Guide.

This manual is not a complete description of the object classes that constitute the iTools component framework. We describe the object classes you will use to create new iTools, but not necessarily the building blocks from which those classes are constructed. If you desire a deeper understanding of how the component framework functions than this manual provides, you can inspect the object class definition files, which are provided in IDL subdirectory of your IDL

See “Docu mented vs. Undocumen ted Classes ” on page 13 for a complete e xplanati on of our approach to documenting the iTool component framework.

.pro source code format in the itools/framework

lib directory.

About this Manual iTool Developer’s Guide

Chapter 1: Overview of iTools 13

About the iTools Code Base

The iTools component framework is written almost entirely in the IDL language. The IDL code that implements both the component framework and all of the standard iTools included with IDL is available for you to inspect, copy, and learn from.

To inspect the iTools code, look in the installation directory. The iTools code base is organized as follows:

•In the

lib/itools directory you will find code that implements the iTool

launch routines. These routines can be called directly at the IDL command line to launch a specific iTool.

lib/itools/framework directory you will find the core iTool object

class definitions and utility routines. The classes in this directory define how the iTools operate; the y are made a v aila ble for your ins pection, b ut they shou ld not be altered.

lib/itools/components directory you will f ind de ri ved i Tool object

classes. The classes in this directory implement the non-core features of the iTool toolset as included with IDL. You are encouraged to use these classes to implement your own iTool functionality, either by subclassing from a derived iTool object class or by modifying a copy of the class definition for a derived class.

lib/itools/ui_widgets directory you will find the IDL code that

creates an iTool user interface using IDL widgets. You may find it useful to inspect some of these routines if you are creating a side panel or a dialog used to collect parameter set tings for an operation. See Chapter 11, “iTool User

Interface Architecture” for additional information on creating additional user

interfaces for an iTool.

lib/itools subdirectory of your IDL

Documented vs. Undocumented Classes

If you inspect the lib/itools directory and its subdirectories, you will notice that there are many more classes included in the iTools component framework than are documented in the IDL Refe rence Guide and in this manual. Our approach to documenting the iTools code that is included with IDL is as follows:

• iTool launch routines for iTools included in the IDL distribution are documented in the IDL Reference Guide. Use of the launch routines for the pre-built iTools is discussed in the iTool User’s Guide.

iTool Developer’s Guide About the iTools Code Base

14 Chapter 1: Overview of iTools

• The core iTool component framework classes used to build individual iTools, visualization types, operations, etc. are formally documented in the IDL Reference Guide and discussed in detail in this manual. If an object class, method, or property is necessary for the construction of a new iTool or component of an iTool, it is formally documented in the IDL Reference Guide or in this manual. Core iTool framework classes are located in the

lib/itools/framework subdirecto ry of the IDL installation directory.

• Supporting iTool component framework classes — those used to implement the documented component framework classes — are not formally documented. As noted previously, the code for these classes is available for inspection. Supporting iTool framework classes are located in the

lib/itools/framework subdirecto ry of the IDL installation directory.

• Derived iTool classes — those used to implement individual iTools and their features — are not formally documented. These classes are derived from the formally documented cl asses, and as suc h can be understoo d by referr ing to the formal documentation. Derived iTool framework classes are located in the

lib/itools/components subdirectory of the IDL installation directory.

• iTool user interface routines are not formally documented. These routines use standard IDL widget programming techniques, and as such can be understood by referring to the IDL widget documentation. User interface routines are located in the

lib/itools/ui_widgets subdirectory of the I DL inst allatio n

directory.

Warning on Using Undocumented Features

While you are encouraged to inspect the iTools code, and to copy or subclass from deriv ed classes and user interface routines, be aware that classes and routines that are not formally documented are not guaranteed to remain the same from one release of IDL to the next. Keep the following points in mind when implementing your own iTools:

• ITT Visual Information Solutions will change undocumented supporting classes as necessary to improve the iTools system.

• ITT Visual Information Solutions may also change undocumented derived classes to fix problems or add functionality; in these cases, we will make every effort to preser ve backwards compatibility, but this is not guar anteed.

If you create new iTool classes based only on the formally documented iTool interfaces, your tool s should operat e pro perly wit h fut ure r eleas es of IDL. If y ou base your tools on undocumented derived classes, minor modifications may be necessary to ensure futu re compatibility.

About the iTools Code Base iTool Developer’s Guide

Chapter 1: Overview of iTools 15

Skills Required to Use the iTools Component Framework

The iTools component framework consists of a set of IDL object classes, supplemented by utility routines. If you are already familiar with the concepts of object-oriented prog ramming, or ha v e written programs that use IDL object gra phics, you will find the iTools framework easy to understand and use. The framework approach means that most of the details of creating a full-featured and usable application are already taken care of, leaving you free to concentrate on how best to manipulate and visualize your data.

If you are familiar with procedural programming in IDL but new to object-oriented programming, you will fi nd de v eloping iTools to be a gentle introduction to the topic. The iTools framework has been designed to allow IDL users with little or no experience wr iting objec t-ori ented progra ms to ea si ly cust omize a nd e xtend the ba si c iTool applications. While some familiarity with the concepts of object-oriented programming is necessary to successfully develop iTools, you should be able to create simple modifications of existing tools almost immediately, and more complex customizations soon thereafter.

iTool Developer’s Guide Skills Required to Use the iTools Component Framework

16 Chapter 1: Overview of iTools

Skills Required to Use the iTools Component Framework iTool Developer’s Guide

Part I: Understanding

the iTools Component

Framework

Chapter 2

iTool System Architecture

This chapter describes the iTool component framework architecture.

Overview of the iTool System Architecture 20

iTools Object Model Diagram . . . . . . . . . . . 21

iTool Object Identifiers . . . . . . . . . . . . . . . . 28

iTool Ob ject Hierarchy . . . . . . . . . . . . . . . . 31

iTool Developer’s Guide 19

Registering Components . . . . . . . . . . . . . . 38

iTool Messaging System . . . . . . . . . . . . . . 41

System Resources . . . . . . . . . . . . . . . . . . . . 44

20 Chapter 2: iTool System Architecture

Overview of the iTool System Architecture

The iTool system architecture is designed to maintain a separation between the functionality provided by an iTool and the graphical presentation layer that reveals that functio nality to an iTool user (the iTool user interface). Such a se paration allows for the creation of different user interface s for the same underlying f unctionality ; while the initial iTool user interface has be en created usi ng IDL widget s, it is easy to imagine using other technologies to create an interface to the underlying iTool functionality.

To support the goal of enabling different user interfaces for a given set of iTool functionality, the iTool architecture includes the following features:

• A design in which a sing le iTool object (based on the IDLitTool class) contains all non-interactive tool functional it y. Similarly, a singl e iTool object (based on the IDLitUI class) cont ains all user interface functionality. This division is clearly visible in the “iTools Object Model Diagram” on page 21.

•An object identifier system that provides a platform-neutral way to identify objects across process and machine boundaries. Additionally, the object identifier system is designed to work with existing component technologies such as COM and Java.

• A minimal connection between the non-interactive tool functionality and the presentation layer. The tool architecture provi des a small set of highly abstract methods that the tool and presentation layer use to communicate with each other. This minimal connection means that the presentation layer needs only a single object reference to the iTool object itself.

•A messaging system that allows one component to observe another, receiving notification messages when the observed component changes in some way.

This chapter describes some of the core ideas of the iTool system: component

inheritance, object identifiers, the iTool system object and the object hierarchy it contains, the concept of registration, and how information is passed between iTool components.

Overview of the iTool System Architecture iTool Developer’s Guide

Chapter 2: iTool System Architecture 21

Figure 2-1: iTools Object Model Hierarchy

The following figure shows inheritance among the iTools component object classes that define the base

functionality of all iTools. The diagram is intended to pro vide a visual overview of the structure of the iTools,

and to provide a quick indication of the methods and properties available to objects of a given class. See the

IDL Reference Guide for details regarding the available properties and methods of these components.

iTools Object Model Diagram

iTool Developer’ s Gu ide iTools Object Model Diagram

22 Chapter 2: iTool System Architecture

Every iTool is constructed using the hierarchy of predefined and documented object classes shown in the previous figure. Each of these predefined (as opposed to userdefined) object classes are available to use or customize in your iTool application. However, there is no need to create and instantiate the entire hierar chy when creating a custom iTool object.

Launching an iTool application creates instances of objects in the iTools class hierarchy, as well as others subclassed from the predefined classes. Developing an application that subclasses from the IDLitToolBase class automatically includes the functionality of parent object classes, such as IDLitTool, and IDLitIMessaging. This will also include and register manipulator and operation objects that are common among the predefined iTools. Unwanted items can be unregistered. Other predefined objects are instantiated as needed. For example, an iTool application may be started without a data argument. Only when data is imported into the tool is a predefined or custom IDLitVisualization object created to contain the data. For instance, an IDLitVisPlot object is instantiated when data is imported into the iPlot tool, which may or may not be when the tool is initiated.

Once the hierarchy of component objects have been instantiated, there is no need to maintain a long list of object references to access and manipulate individual objects. Each component is assigned an identifier when it is instantiated; an identifier is a simple stri ng that can be used to access an object (such as an IDL ItVisPlot object) in order to change prope rtie s, appl y opera tions , or mak e ot her modi f icat ions. See “iTool

Object Identifiers” on page 28 for details.

The following sections further describe the chain of inheritance followed by the objects that make up a particular iTool. The classes listed below are subclassed from the iTool object classes shown in the “iTools Object Model Diagram” on page 21. With the e xce ption of the atomic gr aphic obj ects (l ist ed in “Atomic Graphic Objects” on page 26), these subclasses are not documented and are subject to change. While we encourage you to inspect these undocumented subclasses and use them as examples when creating your own subclasses, we discourage you from subclassing from them directly.

Note

ITT Visual Information Solutions may add, change, or remove undocumented subclasses of the documented iTools classes at any time. The following lists may not exactly match the set of subclasses shipped with any particular version of IDL.

Except for the at omic gr aphic o bject s, a ll of th e c lasse s lis ted be low are written in the IDL language. Their definitions can be found in the

lib/itools/components

subdirectory of your IDL installation. See “About the iTools Code Base” on page 13

iTools Object Model Diagram iTool Developer’s Guide

Chapter 2: iTool System Architecture 23

for additional in formation about iTools code and the differences be tween documented and undocumented classes.

IDLitVisualization Classes

The IDLitVisualization class provides methods for adding, deleting, and grouping objects within a visualization. The following predefined classes contain graphic objects and other visualiza tions. F or e xample, the I DLitVisPlot is a container for plot, symbol, and selection visual obj ects as well as other items that as a group, pro vide the complete visual representation of the plot data. See Chapter 6, “Creating a

Visualization” for details.

• IDLitVisAxis • IDLitVisPlotProfile

• IDLitVisColorbar • IDLitVisPlot3D

• IDLitVisContour • IDLitVisPolygon

• IDLitVisHistogram • IDLitVisPolyline

• IDLitVisImage • IDLitVisROI

• IDLitVisIntVol • IDLitVisShapePoint

• IDLitVisIsoSurface • IDLitVisShapePolygon

• IDLitVisLegend • IDLitVisShapePolyline

• IDLitVisLight • IDLitVisSurface

• IDLitVisLineProfile • IDLitVisText

• IDLitVisMapGrid • IDLitVisVolume

•IDLitVisPlot

IDLitTool Classes

The IDLitTool class provides the iTools system infrastructure used by every iTool. All of the sta ndar d iTools are based on a subc la ss of IDLitTool called IDLitToolbase. The IDLitToolbase class provides all of the base functionality found in the standard iTools including menu items, file readers and writers, operations, and manipulators. See “Subclassing from the IDLitToolbas e Class” in Chapter 5 for more information

iTool Developer’s Guide iTools Object Model Diagram

24 Chapter 2: iTool System Architecture

on included functionality. See the iTool User’s Guide for information on using individual iTools.

• IDLitToolContour (iContour tool) • IDLitToolSurface (iSurface tool)

• IDLitToolImage (iImage tool) • IDLitToolVolume (iVolume tool)

• IDLitToolMap (iMap tool) • IDLitToolVector (iVector tool)

• IDLitToolPlot (iPlot tool)

IDLitData Classes

The IDLitData class stores core IDL data types, gets and sets data, and receives updates regar ding data cha nges. The predefined IDLitData classes listed in the following table are designed to hold data which can then be displayed in an iTool. See Chapter 3, “Data Management” for details.

• IDLitDataIDLArray2D • IDLitDataIDLPalette

• IDLitDataIDLArray3D • IDLitDataIDLPolyVertex

• IDLitDataIDLImage • IDLitDataIDLVector

• IDLitDataIDLImag eP ix e ls

IDLitReader Classes

The IDLitReader cl ass co ntains pr edef ined f ile reade rs that determin e the typ e of d ata being accessed, and create an IDLitData object to contain the data. See Chapter 9,

“Creating a File Reader” for details on creating and using file readers.

• IDLitReadASCII • IDLitReadJPEG2000

• IDLitReadBinary • IDLitReadPICT

• IDLitReadBMP • IDLitReadPNG

• IDLitReadDICOM • IDLitReadShapefile

• IDLitReadISV • IDLitReadTIFF

• IDLitReadJPEG • IDLitReadWAV

iTools Object Model Diagram iTool Developer’s Guide

Chapter 2: iTool System Architecture 25

IDLitWriter Classes

The IDLitW riter class co ntains prede fined file writers tha t export graphi cs or data to a file of a specified type. See Chapter 10, “Creating a File Writer” for details on creating and using file writers.

• IDLitWriteASCII • IDLitWriteJPEG

• IDLitWriteBinary • IDLitWriteJPEG2000

• IDLitWriteBMP • IDLitWritePICT

• IDLitWriteEMF • IDLitWritePNG

• IDLitWriteEPS • IDLitWriteTIFF

• IDLitWriteISV

IDLitOperation Classes

The IDLitOperation class defines an action on data, or a change to an iTool visualization. Transaction recording provides undo/redo capabilities. See Chapter 7,

“Creating an Operation” for information on creating a new operation or using

predefined operations.

• IDLitOpBytscl • IDLitOpCurveFitting

• IDLitOpConvolution • IDLitOpSmooth

Note

There are many additional operations (named with the prefix “idlitop”) in the

lib\itools\components subdirecto ry of your IDL installation.

IDLitManipulatorContainer Classes

The IDLitManipulatorContainer class provides a container for a group of manipulators, among which an active manipulator may be set. The following manipulator conta iners are p redef i ned. The manipul ator s held within ea ch pre def ine d container are described in “Predefined iTool Manipulators” on page 198.

• IDLitManipArrow • IDLitManipRotate

• IDLitManipRange

iTool Developer’s Guide iTools Object Model Diagram

26 Chapter 2: iTool System Architecture

IDLitManipulator Classes

The IDLitManipulator class allows the user to select and interact with a visualization through mouse movements and keyboard events. See Chapter 8, “Creating a

Manipulator” for information on the following predefined manipulators and creating

a new manipulator.

• IDLitAnnotateFreehand • IDLitManipRangePan

• IDLitAnnotateLine • IDLitManipRangeZoom

• IDLitAnnotateOval • IDLitManipRotate3D

• IDLitAnnotatePolygon • IDLitManipRotateX

• IDLitAnnotateText • IDLitManipRotateY

• IDLitManipAnnotation • IDLitManipRotateZ

• IDLitManipCropBox • IDLitManipScale

• IDLitManipImagePlane • IDLitManipSelectBox

• IDLitManipLine • IDLitManipSurfContour

• IDLitManipROIFree • IDLitManipTranslate

• IDLitManipROIOval • I DLitManipView

• IDLitManipROIPoly • IDLitManipViewPan

• IDLitManipROIRect • IDLitManipViewZoom

• IDLitManipRangeBox

Atomic Graphic Objects

In addition to IDLgrModel and IDLgrWindow objects shown in the “iTools Object

Model Diagram” on page 21, the following IDL objects inherit from

IDLitComponent:

• IDLgrAxis • IDLgrPolyline

• IDLgrContour • IDLgrROI

• IDLgrImage • IDLgrROIGroup

• IDLgrLight • IDLgrSurface

iTools Object Model Diagram iTool Developer’s Guide

Chapter 2: iTool System Architecture 27

• IDLgrPlot • IDLgrText

• IDLgrPolygon • IDLgrVolume

iTool Developer’s Guide iTools Object Model Diagram

28 Chapter 2: iTool System Architecture

iTool Object Identifie rs

iTool object identifiers are simple strings that uniquely identify individual objects within the hierarchy of iTool objects in much the same way that a computer file system identifies files within a hierarchy of files. The object hierarchy (and, by extension, the object identifiers) also describe where information about objects is made visible in the iTool user interface; see “iTool Object Hierarchy” on page 31 for additional discussion of the iTool hierarchy and the iTool system object.

Besides providing a familiar, user-readable way to identify objects in the iTool system, object identifiers also allow iTool developers to refer to an object without having to maintain an actual object reference to that object. This ability to use a lightweig ht string object to refer to a potentially “heavy” object in the iTool system makes it possible to maintain a very loose coupling between the objects that implement an iTool’s functionality and those that implem ent its user in terface. This allows for object access that can cross process and machine boundaries, paving the way for the use of the iTool system in more distributed environ ments.

Note

Object identifiers are not to be confused with object descriptors. See “Object

Descriptors” on page 30 for details.

Object identifier strings are assigned when an object class is registered with either a n individual iTool or with the iTool system object. See “Registering Components” on page 38 for a discussion of the registration process.

Fully-Qualified vs. Relative Identifiers

Identifiers can either be fully qualified, meaning that they depict the entire path from the root iTool system object to the object being identified, or r elative, meaning they depict the path from the root of the current iTool. Fully qualified identifiers begin with the “/” char acter, and refer to o bjects t hat are accessibl e to all iTools that become activ e du ri ng the lifetime of the iTool system object. Relative identifiers do no t begin with a “/” and refer to objects that are accessible only within a specified container object.

For example, the identifier string

/DATA MANAGER/MY DATA

refers to an object named MY DATA, located in the system-level DATA MANAGER container. Because t he identifier is fully qualified, the MY DATA object is visible to any iTool that is active during the iTool session.

iTool Object Identifiers iTool Developer’s Guide

Chapter 2: iTool System Architecture 29

Similarly, the identifier string

OPERATIONS/FILTERS/MY FILTER

refers to an object named MY FILTER, located in a sub-container of the iTool-level

OPERATIONS container named FILTERS. Because the id entifier is relative, the MY FILTER object is visible only to the current iTool.

Note

Object identifiers are stored as upper-case strings. Spaces are allowed.

Using Identifiers

Numerous methods defined by iTools object classes accept object identifiers as arguments t o uniquely identify an ob ject instance. This frees you as a dev el oper from the need to obtain and keep track of an actual object reference for each object you wish to refer to or modify.

For example, the DoSetProperty method of the IDLitTool object class allows you to change the value of an object property by supplying the identifier for the object whose property is to be changed, as well as the identi fier for the property itself. Similarly, the DoAction method of the IDLitTool class allows you to initiate an operation simply by supplying its identifier.

Retrieving Identifiers

At times, you may know the identifier of the object you wish to affect. This is the case when your own code registers an operation, for example; you must supply the identifier when calling the ITREGISTER routine or Register meth od. (See

“Registering Components” on page 38 for additional details.)

Other times, you may not kno w the ide ntif ier of th e object you wish to aff ect. In the se cases, you have two options:

1. If your code has access to the actual object reference to the object whose

identifier you need, you can use the GetFullIdentifier method of the IDLitComponent object class. See “IDLitComponent::GetFullIdentifier” (IDL Reference Guide) for details.

2. If your code does not have access to an object reference, you can use the

FindIdentifiers method of the IDLitTool object class to retrieve a list of identifiers that match a specified pattern. See “IDLitTool::FindIdentifiers” (IDL Reference Guide) for details.

iTool Developer’s Guide iTool Object Identifiers

30 Chapter 2: iTool System Architecture

Proxy Identifiers

Because the location of an object in the iTool object hierarchy corresponds to the place that object is made vi sible to iTool users, you may at times want an object to be located in multiple places in the iTool object hierarchy. For example, the Undo operation appears in two places in the standard iTool user interface: under the Edit menu and on the toolbar. Rather than duplicating the Undo operation object in each of those places in the iTool object hierarchy, we can use a proxy mechanism to register the same object instance with multiple object identifiers. In the case of the Undo operation, the ope ration it self is located in the EDIT subcont ainer of the iTool’s OPERATIONS container, which implies that the operation appears under the iTool’s Edit menu. A proxy (or alias) to this o bject is created i n the EDIT s ubcontain er of the iTool’s TOOLBAR container, which places the operation on the toolbar. Only one instance of the Undo object is created, but its action can be invoked from both the menu and the toolbar.

Proxy identifiers are assigned by the Register method for the object being proxied. See “Registering Components” on page 38 for additional details.

Object Descriptors

Object descriptors are iTool objects that contain enough information about a given object class to create an object of that class when necessary. In many cases, object descriptors, rather than instances of the objects they create, are stored in the iTool hierarchy; this approach allows object instances to be created only when needed. Object descriptors al so manage instance s of objects that can be re-used by th e system, avoiding the need to create a new instance of an object (such as an operation) each time it is used.

Cases in which an iTool developer will need to know about or use object descriptors rather than object identifiers are very rare . We mention object des criptors here because they are used extensively in the iTool object hierarchy to expose the functionality of objects that are created as needed, rather than being created automatically when the iTool is created.

iTool Object Identifiers iTool Developer’s Guide

+ 400 hidden pages