Programmer Reference
Programmer Reference
Preface
Notices
Trademarks
About this book
What's new?
Who this book is for
Conventions used in this book
Tell us what you think
VAST Base overview
Base subsystems
Common Language Data Types
Common Language Implementation
Common Process Model
Common File System
Common Graphics
Common Widgets
Extended Widgets
Drag and Drop
Common Printing
Design intent
Architecture
Industry-standard support
Platform support
Bitness support
Common Language Data Types
Object behavior
Boolean classes
Collection classes
Collection protocols
Common collection protocols
Unique collection protocol
Magnitude classes
Magnitude comparing
Association
Character
Date
Time
Number
Integer
Fraction
Float
ScaledDecimal
Graphical classes
Point
Rectangle
Stream classes
Accessing
Copying
Enumerating
Positioning
Reading
Testing
Truncating
Writing
Creating instances
Support classes
UndefinedObject
Message and DirectedMessage
Block
Exception handling classes
ExceptionalEvent
Signal
Creating new exceptions
Signaling an exception
Handling of exceptions
ExceptionalEvent collections
Completion blocks
Default exception handler
System exceptions
Examples of exception handling
Common Language Implementation
Object messages
Behavior messages
Class messages
Metaclass messages
Creating new classes
Creating fixed classes
Creating variable classes
Creating variable byte classes
Extended classes
Multiple instance accessing
String converting
Compiling and evaluating code
Compiling
Evaluating
CompiledMethod
Accessing
Testing
EmSystemConfiguration
Common Process Model
Creating a process
Suspending, resuming, and ending a process
Setting and modifying process priorities
Synchronization using semaphore and delay
Block evaluation methods
Process-related block methods
Process methods
ProcessorScheduler methods
Delay class and instance methods
Semaphore class and instance methods
Common File System
Accessing the capabilities of the Common File System
Basic file protocols
Stream protocols
Portability protocols
Error handling protocols
CfsConstants pool dictionary
Basic classes
Specifying file names and paths
Portable file names
File system roots
Path separators
Managing files and directories
Current working directory
Creating and removing directories
Deleting files
Renaming files
Copying files
Setting the timestamps of a file
Startup directory
Obtaining volume information
Volume name and type
File names and directory path case
File name length
Volumes with different file name lengths
Searching directories
Opening a directory for searching
Reading directory entries
Closing the directory descriptor
Using file streams
File stream classes
Opening and closing file streams
Reading and writing file streams
Characters versus bytes
Line delimiters
Using low-level file operations
Opening files
Closing file descriptors
Reading and writing data
Changing the file offset
Other low-level operations
Mixing streams and file descriptors
Using access modes and flags with file streams
Performing low-level file operations on streams
File locking and share modes
File locking
Share modes
Handling errors
Suppressing system error dialogs
Testing existence and obtaining other file properties
Obtaining a CfsStat instance
Mixing platform-specific and Common File System operations
Performing a platform-specific call with a CfsFileDescriptor
Converting a platform file descriptor into a CfsFileDescriptor
Obtaining platform-specific error information
Common Graphics
X Window system graphics library compatibility
Core Common Graphics class hierarchy
Seldom-used and abstract classes
A simplified drawing process overview
Before drawing
During drawing
After drawing
A simple example of the drawing process
CgConstants pool dictionary
Using graphics contexts
Basic graphics context methods
Creating graphics contexts
Copying graphics contexts
Changing graphics contexts
Freeing graphics contexts
Using graphics contexts with other drawables
Drawing operations
Drawing points
Drawing lines
Drawing rectangles
Drawing polygons
Drawing arcs and circles
Drawing pie slices and chords using filled arcs
Using fonts
A simplified view of the font process
Querying the system for fonts
Loading fonts
Assigning fonts for use in drawing operations
String drawing operations with fonts
Releasing CgFonts and CgFontStructs from memory
Obtaining the current font from a graphics context
Using cursors
The process for using cursors
Font cursors
Glyph cursors
Pixmap cursors
Changing the color of a cursor
Platform cursors
Using pixmaps
Creating a pixmap using createPixmap:
Creating a pixmap using createPixmapFromBitmapData:
Copying pixmaps to and from windows
Getting pixmap geometry
Creating a bitmap from bitmap data
Creating stipples using bitmaps
Writing bitmaps to files
Reading bitmaps from files
Displaying bitmaps
Common Graphics image support
Specifying colors
Specifying colors as RGB intensities
Specifying colors by name
Parsing a color-specification string
Using palettes
The default palette
Creating indexed palettes
From pixel values to colors and back
Selecting and drawing with palettes
Direct palettes
Device-independent images
Creating and manipulating images
Displaying images
Direct color images
Copying images from a drawable
Icons
Creating icons
Drawing icons
Loading icons from DLLs
Using operating system icons
Image and icon file formats
Loading images from files
Handling errors
Loading icons from files
Unloading images into files
Unloading icons into files
Unloading images and icons into ByteArrays
Loading images and icons from ByteArrays
Determining the format of a file
Extra file format information
Resource management summary
Common Widgets
OSF/Motif compatibility
Common Widgets class hierarchy
Common Widgets class hierarchy
Overview of Common Widgets user interface concepts
The parent-child widget tree
The widget lifecycle
Mapping and unmapping widgets
Managing and unmanaging widgets
Widget resources and functions
CwConstants pool dictionary
Example code to create a widget tree
Widget event handling and callbacks
Example of using an event handler and a callback
Creating and using widgets
Widget creation convenience methods
Callbacks
Event handlers
Shell widgets
Top-level shell widgets
Scrolled-window widgets
Main-window widgets
Main windows and geometry management
Text widgets
Drawing area widgets
Adding an event handler to a drawing area
Layout widgets
Form widgets
Row-column widgets
Button and label widgets
Static label widgets
Push-button widgets
Toggle-button widgets
Radio-button groups
Check boxes
Icon and pixmap label and button widgets
Application-drawn buttons
Menus
Greying out buttons
Simple menus and menu bars
Creating a menu bar and pull-down menu using simple menu protocol
Creating a secondary menu using simple menu protocol
Creating a pop-up menu using simple menu protocol
Non-simple menus and menu bars
Non-simple menu example
List widgets
Single selection lists
Multiple selection lists
Scrolled lists
Combo-box widgets
Composite-box widgets
MessageBox widgets
SelectionBox widgets
Dialog convenience methods
Creating and using prompters
Message prompter
Text prompter
File selection prompter
Extended widgets
Writing an extended widget
Example: a primitive extended widget
Example: a composite extended widget
Fonts
Using the system browser font
Colors
Clipboard operations
Examples for using the clipboard
Platform-integrated drag and drop
Target types
Transferring data
Drag and drop objects
Procs
Common Widgets drag and drop classes
Drag source widgets and the CwDragContext object
Drop site widgets and CwDropSite objects
Data transfer and the CwDropTransfer object
The user interface process model
The system view
The application programmer's view
Examples of applications with long-running operations
Windows Common Controls
CwDateTimePicker
CwMonthCalendar
CwProgressBar
CwRebar
CwStatusBar
CwTabStrip
CwTrackBar
CwTreeView
CwToolBar
CwTable
Column customization
Row creation
Callbacks
# CwWebViewSupport
CwWebViewSupport
## CwWebView
## CwWebViewEnvironmentOptions
Extended Widgets
Extended Widgets class hierarchy
EwConstants pool dictionary
Creation convenience methods
Extended list widgets
Common resources
Scrolled lists
Drawn list widget
Icon list widgets
Renderables
Direct editing of labels
Flowed icon list widget
Icon area widget
Table list widget
Table list resources
Table columns
Direct editing of cell values
Edit policies
Tree widgets
Icon trees
Table trees
Notebook widgets
Creating pages
Callbacks
PM notebook widget
WIN notebook widget
Progress bar widget
Slider widget
Spin button widget
Split window widget
Tool bar widget
Creating tools
Using tools
Drag and Drop
Drag and drop adapters
Sequence of events
Voting and cursors
Source vote and image changes
Leaving a target
Dropping
Canceling a drag
System configuration
Simple drag and drop
Widget limitations
Common Printing
Common Printing classes
Printing process overview
Selecting a printer
Configuring print job attributes
Creating a print job
Using the printer prompter
Print job attributes
Using a printer shell
Creating a shell
Adding callbacks
Starting a job
Producing a page
Ending a job
CwPrinterShell resources and convenience methods
Printing with Common Graphics
A complete example
Setting up printers and queues on UNIX platforms
Configuring printer setup options
Printer configuration information
Pragmas
Namespace pragmas
Namespaces
Scope rules
Namespace management
Declarations
Declaration methods
Declaration syntax
Working with declaration methods
Why use declaration methods?
Where to declare?
When several applications contribute to a pool
Placement of declarations
Platform-dependent declarations
Adding, deleting, and changing declarations
Finding declaration methods
Correcting declaration errors
Loading previous editions of applications that do not have declaration methods
File-out format
Annotation pragmas
Including an Annotation Pragma in a Method
Processing Annotation Pragmas
Collecting Annotation Pragmas
Performing Operations with Annotation Pragmas
Accessing Annotation Pragma Components
VAST Virtual Machine API
Who should read this chapter
Conventions
VAST C programming model
Defined types
Object types
Macros versus functions
External language interface
Parameter types
Calling a PlatformFunction
Inline external function calls
PlatformFunction protocols
PlatformLibrary protocols
Entry points
Parameter types and return types
Calling an EsEntryPoint
EsEntryPoint protocols
Asynchronous callouts
Calling a Platform Function asynchronously
Locking resources for an asynchronous call
ACO errors and error cases
Walkbacks
ACO errors
Parameter types and return types
Managing resources
Extensions to platform function protocols
ACO resource manager protocols
Resource future protocols
Static future protocols
ACO error protocols
OSObjects
OSObject subclasses
OSObject protocols
OSImmediate protocols
OSBaseType, OSObjectPointer, and OSStructure protocols
OSStructure protocols
OSVariableStructure protocols
OSBaseType protocols
ObjectPointer protocols
Methods available in other classes
User primitives
User primitive tables
Functions available in user primitives
Object allocation
Sending messages
Testing objects
Converting Smalltalk objects to C values
Converting C values to Smalltalk objects
Accessing objects
Protecting objects from garbage collection
Miscellaneous
Classes available in user primitives
Asynchronous messages (interrupts)
Using user primitive functions outside user primitives
Sample user primitives for VAST
Sample callback for Microsoft Windows
Example callback code
Smalltalk code that uses the primitive above
Platform requirements
Microsoft Windows
UNIX platforms
Primitive error codes
Cryptography
Introduction
Getting Started
Architectural Overview
Modules
Core
ASN1
Symmetric Ciphers
Error Handling
I/O Abstraction
Message Authentication Code (MAC)
Message Digests
Multiprecision Integer Arithmetics
Public/Private Key
Random Number Generator
X509
UUID
Socket Communications Interface
Introduction
Application Programming Interface
Supported Socket and Database functions
SCI classes
SciAbstractSocket protocols
Instance methods
SciSocket protocols
Instance methods
Class methods: creation
SciLocalSocket protocols
Instance methods
Class methods: creation
SciSocketManager protocols
Instance methods
Class methods: creation
SciSocketAddress protocols
Instance methods
Class methods: creation
SciLocalSocketAddressProtocols
Instance Methods
Class methods: creation
SciReturn protocols
Instance methods
SciError protocols
Instance methods
SciErrorProxy protocols
Instance methods
SciHostEnt protocols
Instance methods
SciProtoEnt protocols
Instance methods
SciServEnt protocols
Instance methods
Error values
Secure Socket Layer (SSL)
Overview
SSL Example Workspaces Certificate and Private Key
Example Workspaces
SSL Server Workspace
SSL Client Workspace
Application Programming Interface
Supported SciSslSocket functions
SciSslSocket Protocols
SciSslContext Protocols
SciSslSocketConfiguration Protocols
SciSslX509Certificate protocols
SciSslPrivateKey protocols
SciSslError protocols
SciSslBlockingDispatcher protocols
The SciSslOpenSSLInterface Subapplication
Licenses
Dynamic data exchange
Introduction
DDE concepts and definitions
DDE classes
DdeClient class
DdeServer class
DdeServerManager class
DdeCallbackData class
Building a DDE server
Building a DDE server that uses default processing
Building a DDE server that does not use default processing
Discussion of the DdeServerManager
Building a DDE client
An example DDE client
Discussion of the DdeClient
Formats of data transferred between DDE servers and clients
Callbacks for handling DDE events
Return values
DDE protocols
DdeServerManager public class methods
DdeServerManager public instance methods
DdeClass public instance methods
DdeServer public instance methods
DdeClient public instance methods
Protocols common to DdeServer and DdeClient
Converting Smalltalk objects to a ByteArray and back
Examples
Spreadsheet
Spreadsheet window coordinates
Two windows exchanging data
Updating time and date
Updating time in the String format
Platform-specific support
National Language Support
Overview of National Language Support
NLS concepts and definitions
The POSIX locale model
Overview of internationalization
Overview of localized messages
Overview of message catalogs
Locating message catalogs
National Language Support classes
Support for double-byte characters
Obtaining Locale, LCCType, and LCCollate objects
Obtaining LCMessages, LCMonetary, LCNumeric, and LCTime objects
NLS-enabled classes
Locale-specific sorting
Number formatting
Locale change notification and the image startup sequence
Tools for developing international software
Externalization support and tools
Catalog File Editor
NLS Enabler
Using message templates
Referencing and initializing localized messages
Overview of the message localization process
Using message catalogs
Using external message dictionaries
Using indexed external messages
Deleting locales from a message catalog file
Support for extended locales
Compatibilities
Compression
Limitations
Error detection and description
Support for platform resource formats
Localization support API
VAST locale names
Manual localization
LCCollate
LCMessages
LCMonetary
LCNumeric
LCTime
Locale
Locales and platform representation
OS/2 Presentation Manager
Microsoft Windows
AIX, HP-UX, and Solaris
# UnicodeSupport
UnicodeSupport
## Autoconversion of String into UnicodeString
EsUnicodeEncoding
EsUnicodeSlice
EsUnicodeStorage
Grapheme
GraphemeView
UnicodeLimitedWriteStream
UnicodeReadStream
UnicodeReadWriteStream
UnicodeScalar
UnicodeScalarView
UnicodeString
Unicode Support
UnicodeView
UnicodeViewPosition
UnicodeWriteStream
Utf16
Utf16BE
Utf16BigEndianView
Utf16LE
Utf16LittleEndianView
Utf16View
Utf32
Utf32BE
Utf32BigEndianView
Utf32LE
Utf32LittleEndianView
Utf32View
Utf8
Utf8View
Asynchronous Programming
Features
EsAsyncArgumentError
EsAsyncError
EsAsynchronousSupport
EsAsyncPromise
EsAsyncScheduleTaskError
EsAsyncStackTrace
EsAsyncStateError
EsAsyncTaskProcessQueueScheduler
EsAsyncTaskScheduler
EsAsyncTimeoutException
EsAsyncUncaughtErrorHandler
EsAsyncUncaughtErrorLayout
EsAsyncZone
EsAsyncZoneSpec
EsFuture
EsFutureImpl
EsFutureListener
EsFuturePropagation
EsPromise
EsSyncPromise
EsAsynchronousStreams
EsEventSink
EsStream
EsStreamChannel
EsStreamIterator
EsStreamPromise
EsStreamSink
EsStreamSinkPromise
EsStreamSubscription
EsStreamTransformer
EsStreamView
EsAsynchronousStreamChannels
EsAsynchronousStreamChannels
EsCloseGuaranteeChannel
EsDefaultStreamChannelBehavior
EsGuaranteeChannel
EsMultiStreamChannel
EsStreamChannelController
EsStreamChannelImpl
EsStreamChannelPromise
EsStreamChannelTransformer
EsVirtualStreamChannel
EsAsynchronousStreamControllers
EsAddStreamState
EsAsynchronousStreamControllers
EsAsyncStreamController
EsStreamController
EsStreamControllerAddStreamState
EsStreamControllerImpl
EsSyncStreamController
EsAsynchronousStreamImpl
EsAsynchronousStreamImpl
EsNullStreamSink
EsPromiseSink
EsAsynchronousStreamPipes
EsAsynchronousStreamPipes
EsAsynchronousStreamTransformers
EsAsynchronousStreamTransformers
EsSingleSubscriptionTransformer
EsAsynchronousStreamVAST
EsAsynchronousStreamVAST
EsByteStream
EsCLDTStreamIterator
EsCollectionIterator
EsSequenceableCollectionIterator
Native Process Framework (OsProcess)
OsNativeProcess
OsNullReadPipeStream
OsNullWritePipeStream
OsPipeline
OsPipelineChain
OsPipelineChainStarter
OsPipelineStarter
OsPipeStream
OsPipeStreamBuffer
OsProcessEnvironment
OsProcesses
OsProcessesApp
OsProcessException
OsProcessFileDescriptor
OsProcessInfo
OsProcessStarter
OsProcessStdioSpec
OsProcessStream
OsReadPipeStream
OsVastProcess
OsVastSubprocess
OsWritePipeStream
Object Linking and Embedding (OLE)
OLE concepts and definitions
OLE classes
OleMainWindow
OlePrimitive
OleClient
OleControl
OleAutomationObject
OleFile
Building an OLE document container
Creating an OLE main window
Creating OLE clients
Enabling clipboard operations
Creating an object verb menu
Invoking the Links dialog
Saving and retrieving an OLE client
Using OLE automation
Creating OLE Automation Objects
Invoking methods of OLE automation objects
Getting and setting properties
Releasing an OLE automation object
Using OLE custom controls (OCXs)
Creating the OLE main window
Creating OCXs
Implementing an ambient-property handler
Using automation aspects of an OCX
Implementing event handlers
Wrapping OCXs with extended widgets
Using licensed OCXs
Log4s
The Players
The Director: LogManager
Specifying the Log Entry
Log4s Error Handling
Initializing the log4s Framework
Ini File Entries
Custom Loggers
Debug Messages
What Gets Logged
Where Log Entries Go
What appears in a log entry
Programmatic Initialization
Creating Custom Loggers
Customizing Debug Message Settings
Customizing What Gets Logged
Redirecting Log Entries
What appears in a log entry
Programmatic Specification of Logging
Sample Application Example
Time Zones
Examples:
Time Zone Database
The DateAndTime class
Time Zone Database
Error Handling and Trouble Shooting
Updating Zoneinfo Data
Data Compression and Decompression
Compression Examples
LDAP
Overview
Setting up the Example
The LDAP Players
LDAP session
LDAP entry structure
LDAP search
Creation
Search Specification
Search execution
Search interrogation
LdapEntry Operations
Timed Wait
Examples
Appendix A. Widget resources and callbacks
Appendix B. Extended widgets resources and callbacks
Appendix C. Drag and drop resources and callbacks
Appendix D. Common graphics platform differences
Appendix E. Common widgets platform differences
References
Common Language Data Types, Common Language Implementation, and Common Process Model
Common File System
Common Graphics
Common Widgets
Common Printing
Dynamic Data Exchange
National Language Support
Index