Dictionary Services Reference

Derived from	CFType
Framework	CoreServices/CoreServices.h, Carbon/Carbon.h
Companion guide	Dictionary Services Programming Guide
Declared in	DictionaryServices.h MacApplication.h

Overview

Dictionary Services provides functions that let you access dictionaries programmatically from within your application. There are three functions described in this reference. Two of them are defined in the Core Services framework; the third is defined in the Carbon framework.

A dictionary is any look-up reference that is built using the Dictionary Development Kit. The contents of a dictionary can serve many purposes. The most typical use is to provide definitions for a single language, but you can create content for a thesaurus, bilingual dictionaries (such as English-Japanese), in-house glossaries, and professional dictionaries (such as legal, medical, and technical).

Functions by Task

Searching Dictionaries

Displaying Dictionary Results

Functions

DCSCopyTextDefinition

Returns the definition associated with the provided text range.

CFStringRef DCSCopyTextDefinition (
   DCSDictionaryRef dictionary,
   CFStringRef textString,
   CFRange range
);

Parameters

dictionary

This parameter is reserved for future use, so pass NULL. Dictionary Services searches in all active dictionaries.

textString

Text that contains the word or phrase to look up.

range

A range that specifies the location of the word or phrase in the textString parameter. If text string exactly specifies the word or phrase that you want to look up, you can pass the range of the text string. For example, for the word make, you would pass (0,4) to specify the range.

If the textString parameter contains the word or phrase, but does not specify it exactly, then pass the range returned by the function DCSGetTermRangeInString.

Return Value

The definition of the word or phrase, as plain text. The returned text does not contain any elements that are marked with a priority attribute whose value is 2.

Discussion

This function returns the description of the first matching record found in the the active dictionaries. It searches first in the default word definition dictionary which, in the English environment, is the Oxford dictionary.

Availability

Available in OS X v10.5 and later.

Declared In

DictionaryServices.h

DCSGetTermRangeInString

Determines the range of the longest word or phrase with respect to an offset.

CFRange DCSGetTermRangeInString (
   DCSDictionaryRef dictionary,
   CFStringRef textString,
   CFIndex offset
);

Parameters

dictionary: This parameter is reserved for future use, so pass NULL. Dictionary Services searches in all active dictionaries.
textString: Text that contains the word or phrase to look up.
offset: A character offset in the textString parameter.

Return Value

The range that specifies the location, around the specified offset, of the word or phrase , or the constant kCFNotFound.

Discussion

You can use this function to determine the range of text that contains a word or phrase. After you determine the range, you can pass the result to the functions DCSCopyTextDefinition and HIDictionaryWindowShow.

To see how this works, follow these steps:

In OS X v10.5 or later, open Text Edit.
Type It is a foggy day in San Francisco, California.
Control-click Francisco (don’t select it). Then, choose “Lookup in Dictionary”.

Note that the Dictionary window appears with a definition of San Francisco. The function DCSGetTermRangeInString automatically detected the range of the phrase San Francisco, using Francisco as the text string to search for and a character offset in this string. The function expanded the range until it found a possible match.

You can also point the cursor at the word Francisco and, without making a selection or clicking, type Command-Control-D. DCSGetTermRangeInString detects the range.

The function DCSGetTermRangeInString only returns the range. You must call DCSCopyTextDefinition to copy the definition and HIDictionaryWindowShow to display the definition in a Dictionary window.

Availability

Available in OS X v10.5 and later.

Declared In

DictionaryServices.h

HIDictionaryWindowShow

Displays dictionary search result in a dictionary window.

void HIDictionaryWindowShow( DCSDictionaryRef dictionary,
   CFTypeRef textString,
   CFRange selectionRange,
   CTFontRef textFont,
   CGPoint textOrigin,
   Boolean verticalText,
   const CGAffineTransform *viewTransform );

Parameters

dictionary: This parameter is reserved for future use, so pass NULL. Dictionary Services searches in all active dictionaries.
textString: Text that contains the word or phrase to look up specified as one of the following: a CFString object, a CFAttributedString object, or a CFData object that contains text in Rich Text Format. Dictionary Services uses the text attributes to draw the title of the dictionary window. If you provide the text string as a CFString object, you must also provide a display font in the textFont parameter.
selectionRange: If you are using this function to show the results associated with text selected by the user, then provide the selection range of the textString parameter. If you are using this function to show the results associated with calling the DCSGetTermRangeInString function, then provide the range returned by that function.
textFont: The Core Text font to use for the title of the dictionary window. You must provide a font only when the textString parameter is a CFString object; otherwise Dictionary Services ignores this parameter.
textOrigin: The origin, in screen pixels, of the typographic baseline of the characters specified by the selectionRange parameter. The top left of the screen is (0, 0).
verticalText: This parameter is reserved for future use. Dictionary Services draws the text in a horizontal orientation regardless of whether you pass true or false.
viewTransform: The affine transformation matrix to apply to the window that contains the text string. Pass NULL to use the identity matrix. Use this to align the dictionary window with the original text. You can only apply a scaling transform; you cannot apply other types of transformations.

Discussion

This function opens a window to display the definition of a word or phrase.

Availability

Available in OS X v10.5 and later.

Declared In

MacApplication.h

Data Types

DCSDictionaryRef

An opaque object that represents a dictionary file.

typedef const struct __DCSDictionary* DCSDictionaryRef;

Discussion

This data type is reserved for future use.

Availability

Available in OS X v10.5 and later.

Declared In

DictionaryServices.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.