Mac Developer Library

Developer

CoreServices Framework Reference Dictionary Services Reference

Options
Deployment Target:

On This Page
Language:

Dictionary Services Reference

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

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

    Declaration

    Swift

    func DCSGetTermRangeInString(_ dictionary: DCSDictionary!, _ textString: CFString!, _ offset: CFIndex) -> CFRange

    Objective-C

    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:

    1. In OS X v10.5 or later, open Text Edit.

    2. Type It is a foggy day in San Francisco, California.

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

    Import Statement

    Objective-C

    @import CoreServices;

    Swift

    import CoreServices

    Availability

    Available in OS X v10.5 and later.

  • Returns the definition associated with the provided text range.

    Declaration

    Swift

    func DCSCopyTextDefinition(_ dictionary: DCSDictionary!, _ textString: CFString!, _ range: CFRange) -> Unmanaged<CFString>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Swift

    import CoreServices

    Availability

    Available in OS X v10.5 and later.

  • Displays dictionary search result in a dictionary window.

    Declaration

    Swift

    func HIDictionaryWindowShow(_ dictionary: DCSDictionary!, _ textString: AnyObject!, _ selectionRange: CFRange, _ textFont: CTFont!, _ textOrigin: CGPoint, _ verticalText: Boolean, _ viewTransform: UnsafePointer<CGAffineTransform>)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.5 and later.

Data Types

  • An opaque object that represents a dictionary file.

    Declaration

    Swift

    typealias DCSDictionaryRef = DCSDictionary

    Objective-C

    typedef const struct __DCSDictionary* DCSDictionaryRef;

    Discussion

    This data type is reserved for future use.

    Import Statement

    Objective-C

    @import CoreServices;

    Swift

    import CoreServices

    Availability

    Available in OS X v10.5 and later.