CREATE_CURSOR

The CREATE_CURSOR function creates an image array from a string array that represents a 16 by 16 cursor. The returned image array can be passed to the REGISTER_CURSOR procedure Image argument. This allows you to quickly design a cursor using a simple string array.

Syntax

Result = CREATE_CURSOR( StringArray [, HOTSPOT=variable] [, MASK=variable])

Return Value

Translates the input string array into an image that satisfies the Image argument of the REGISTER_CURSOR procedure.

Arguments

StringArray

This must be a 16 element string array of 16 characters each that represents a window cursor. The array can consist of the "#" character, space and non-space characters, and optionally, a "$" character as follows:

The "#" characters define the black outline of the cursor.

Any non-space characters define the shape of the white mask. Adding a mask ensures the cursor's visibility in light and dark areas of a visualization. Use the MASK keyword to return the array of masked out values.

The "$" defines a hot spot. Use the HOTSPOT keyword to return the location of this character within the string array.

Keywords

HOTSPOT

Set this keyword to a variable that will contain a two-element vector indicating the location of the "$" character in the StringArray. This is considered to be the mouse position of the cursor. If there is no "$" present, then [0,0] is returned. This variable can be directly passed to the HOTSPOT keyword of REGISTER_CURSOR.

MASK

Set this keyword to return a 16 by 16 byte array containing any non-space characters, which indicates the area to be masked out. This variable can be passed to the MASK keyword of REGISTER_CURSOR.

Examples

The following code creates a simple cursor. Define a string array representing the body and mask portions of the cursor. Notice the hotspot ("$") in the cursor structure.

strArray = [ $ 
        '       .        ', $ 
        '      .#.       ', $ 
        '     .###.      ', $ 
        '    .#####.     ', $ 
        '   ....#....    ', $ 
        '  .#. .#. .#.   ', $ 
        ' .##...#...##.  ', $ 
        '.######$######. ', $ 
        ' .##...#...##.  ', $ 
        '  .#. .#. .#.   ', $ 
        '   ....#....    ', $ 
        '    .#####.     ', $ 
        '     .###.      ', $ 
        '      .#.       ', $ 
        '       .        ', $ 
        '                '] 
cursor_image = CREATE_CURSOR(strArray, HOTSPOT=hotspot, MASK=mask) 
REGISTER_CURSOR, 'translate', cursor_image, HOTSPOT=hotspot, $ 
   MASK=mask

After registering a cursor, you can set the current cursor using the IDLgrWindow::SetCurrentCursor method. The previous string results in the following cursor.

Figure 5-16: String Array Translated into a Cursor

Version History


6.1	Introduced