Isomorphic SmartClient Widgets Guide Version 5.2 Making web applications work as well as desktop applications. Contents copyright ©2000 - 2005 by Isomorphic Software, Inc., and its licensors. All rights reserved by respective owners. The information and technical data contained herein are licensed only pursuant to a license agreement that contains use, duplication, disclosure and other restrictions; accordingly, it is “Unpublished-rights reserved under the copyright laws of the United States” for purposes of the FARs. Isomorphic Software, Inc. 109 Stevenson Street, Level 4 San Francisco, CA 94105-3475 U.S.A. Web: www.isomorphic.com Email: [email protected] Notice of Proprietary Rights The program and documentation are copyrighted by and proprietary to Isomorphic Software, Inc. and its licensors. Isomorphic Software, Inc. and its licensors retain title and ownership of all copies of the program and documentation. Except as expressly licensed by Isomorphic Software, Inc. or as otherwise agreed to by Isomorphic Software, Inc. in writing, you may not use, copy, disseminate, distribute, modify, disassemble, decompile, or otherwise reverse engineer, sell, lease, sublicense, rent, give, lend, or in any way transfer, by any means or in any medium, the program or this documentation. You agree to hold the program and documentation in confidence and to take all reasonable steps to prevent its unauthorized disclosure. 1. These documents may be used for informational purposes only. 2. Any copy of this document or portion thereof must include the copyright notice. 3. Commercial reproduction of any kind is prohibited without the express written consent of Isomorphic Software, Inc. 4. No part of this publication may be stored in a database or retrieval system without prior written consent of the publisher. Trademarks and Service Marks Isomorphic Software and all Isomorphic-based trademarks and logos that appear herein are trademarks or registered trademarks of Isomorphic Software, Inc. All other product or company names that appear herein may be claimed as trademarks or registered trademarks by their respective manufacturers or owners. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All other names are used for identification purposes only and are trademarks or registered trademarks of their respective companies. THE INFORMATION CONTAINED HEREIN IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. SC01v4.0d03.05.2003 C ONTENTS Preface ....................................................................................... 1 Audience ........................................................................................................... 2 Prerequisites ..................................................................................................... 2 How to use this guide ....................................................................................... 2 Summary of chapter contents .................................................................... 3 What this guide does not cover .................................................................. 4 Resources ......................................................................................................... 4 SmartClient Online Reference ................................................................... 4 Sample applications ................................................................................... 4 Updates to documentation ......................................................................... 5 Related readings ......................................................................................... 5 Icons and conventions used in this guide ........................................................ 5 Identifier icons ........................................................................................... 5 Font conventions ........................................................................................ 6 1. Widgets Overview ............................................................................ 7 Why use widgets? ............................................................................................. 8 Creating widget instances ................................................................................ 9 JavaScript vs. XML ................................................................................... 11 Including a separate XML file ............................................................. 12 Manipulating widget instances ....................................................................... 13 Referring to widget instances ......................................................................... 14 Widget containment and attachment—children and peers ............................ 15 Nesting children within a parent widget declaration ............................... 18 Isomorphic SmartClient Widgets Guide iii Table of Contents Example: Widget containment and attachment .......................... 19 Widget contents .............................................................................................. 20 JavaScript debugging ...................................................................................... 21 Using the log system statically and in class instances ............................. 23 Setting logging priorities for categories and classes ................................ 25 2. Drawing Widgets ............................................................................ 27 Specifying initial position and size ................................................................ 28 Drawing .......................................................................................................... 28 Drawing-related methods ........................................................................ 29 Controlling position and size ......................................................................... 30 Example: Dynamic positioning and sizing .................................. 32 Showing and hiding ........................................................................................ 34 Opacity ...................................................................................................... 35 Layering .......................................................................................................... 35 Example: Dynamic layering ......................................................... 36 Clipping and scrolling .................................................................................... 36 Example: Widget overflow (clipping and scrolling) .................... 38 Other visual properties ................................................................................... 39 3. Handling Events .............................................................................. 41 The ISC event model ...................................................................................... 42 Example: Event propagation ....................................................... 43 Handling Page events .................................................................................... 44 Registering keypress events ........................................................................... 46 Example: Keypress Handling ...................................................... 47 Special keys .............................................................................................. 48 Handling widget events .................................................................................. 48 Enabling and disabling widgets ................................................................ 51 Default widget event handlers ................................................................. 52 Mouse events .................................................................................................. 53 Getting event details ....................................................................................... 54 Example: Getting event details ..................................................... 55 Drag-and-drop operations ............................................................................. 56 Dragging and events .................................................................................. 57 Drag appearance ....................................................................................... 57 Setting the drag tracker ...................................................................... 58 Drag repositioning ................................................................................... 59 Example: Drag appearance .......................................................... 60 Drag resizing ............................................................................................. 61 Drag resizing from a sizer button ...................................................... 63 Example: Drag resizing ................................................................ 64 Custom drag-and-drop operations .......................................................... 65 Using the drag tracker with a custom drag ........................................ 66 Drop operations ....................................................................................... 66 Checking