Application Development

This chapter shows how to evaluate and process mouse events, mouse data, and contextual information. Topics include:

• Trapping mouse events.

• Using Panther library functions to get mouse data, such as the location of the mouse click and which buttons were pressed.

• Getting and modifying the mouse pointer's state.

Trapping Mouse Events

You can intercept single and double mouse clicks on an application-wide basis through Panther's key change hook function. You can also intercept double clicking on an individual widget through its Double Click property. Both techniques are discussed in the sections that follow.

Using Key Change Functions

With Panther's key change hook function, you can intercept single and double mouse clicks throughout the program. Panther's key file (smkeys.h) defines these two events through the logical keys MOUS for single mouse clicks, and MDBL for double clicks. A key change function that tests for these logical keys can use Panther library functions to examine the state of the mouse cursor and mouse buttons, and perform special processing accordingly.

For example, the following code shows in skeletal format a key change function that tests for a single click mouse event outside a field, and then determines which button, if any, is down. It also conditionally tests for different combinations of mouse events with keyboard modifiers, such as Shift+click versus Ctrl+click. Most of the processing relies on sm_ms_inquire to test the mouse's state. For detailed information on using this function, refer to page 47-4. For more information on key change functions, refer to page 44-36.

int keychg ( int which_key )

Several widget types have the double_click property, which lets you specify an action that is triggered by double clicking on a widget. double_click gets a control string as its value. This control string can specify to call a function, invoke an operating system command, or open another screen.

The following widget types have the double_click property:

• Single line text

• Dynamic label

• Combo box

• List box that is a select-any type or is defined as a selection group

• Multiline text

Getting Mouse Data

Panther provides library functions and application properties that get information about the mouse's current state:

• The mouse click's location

• The state of the mouse buttons

• Other keys that were pressed when the mouse click occurred

• The amount of elapsed time between mouse clicks

Determining Mouse Click Location

The library function sm_ms_inquire lets you test the last mouse click's line and column location on a Panther screen or on the physical display. Several runtime properties also offer access to the field and screen on which the last mouse click occurred.

Identifying Mouse Coordinates

To determine the line and column location of the last mouse click, supply sm_ms_inquire with arguments of MOUSE_LINE and MOUSE_COLM, respectively. To get the mouse click's line and column within a Panther screen, supply MOUSE_FORM_LINE and MOUSE_FORM_COLM. For example, the following routine gets the mouse click coordinates on a map that is displayed on a static label:

void get_mouse_coords( void )

The previous example also uses sm_ms_inquire and sm_prop_get_str to test whether a mouse click occurred inside a field and the field's identity:

if ( sm_ms_inquire( MOUSE_FIELD ) > 0 && 

When supplied an argument of MOUSE_FIELD, sm_ms_inquire returns either the field number in which the mouse click occurred, or -1 if the mouse click occurred outside the field.

You can also use these runtime properties to get the name of the field and occurrence in which a mouse click occurred:

• mouse_field and mouse_field_name respectively get the number and name of the field in which the last mouse click occurred.

• mouse_field_occ gets the number of the occurrence in which the last mouse click occurred.

All mouse properties are application-level properties, accessible through the @app() modifier. For example, this all-purpose code obtains the data in the last clicked-on occurrence of any field:

vars data

mouse_form_name is an application runtime property that gets the name of the screen on which a mouse click occurred. Like other mouse properties, it is accessible through the @app() modifier as in this example:

vars mouse_screen

You can get the state of each mouse button—up, down, just pressed, or just released—by supplying sm_ms_inquire an argument of MOUSE_BUTTONS. If successful, the function returns an integer bit mask. The function puts the requested data in three segments of three bits each, where each segment represents one of three mouse buttons—left, middle, and right. The three lowest-order bits contain left button data; if the mouse has only one button, only these bit settings are significant. The middle three bits contain right button data. The three highest-order bits contain data for the middle button, if any.

Each bit within a three-bit segment can be set as follows, from lowest- to highest-order bit:

• 0/1Up/down

• 1 Just pressed

• 1 Just released

For example, the bit settings returned for a just-initiated point and click operation—left button is down and just pressed—can be represented as follows:

A click and drag operation that is in progress—right button is down—can be represented like this:

Only four combinations of bit settings are meaningful to Panther and recognized as representing valid button states:

• Up—0 0 0

• Down—0 0 1

• Down and just pressed—0 1 1

• Up and just released—1 0 0

For example, the following routine tests whether any mouse buttons are down: it bitwise AND's sm_ms_inquire's return value with 0x49, thereby masking off all but the first, fourth, and seventh-order bits:

/*find out whether any button is down */

By supplying sm_ms_inquire with an argument of MOUSE_SHIFT, you can find out whether a mouse click occurred with one or more of these keys pressed down: Shift, Ctrl, and Alt. The function returns an integer bit mask whose three lowest-order bits are set to indicate which of the three keys, if any, were pressed. These bits are set as follows, from lowest- to highest-order bit:

• Shift key is down

• Ctrl key is down

• Alt key is down

For example, a return value of 2 (0 1 0) indicates that the Ctrl key is down, while a return value of 5 (1 0 1) indicates that the Alt and Shift keys are both down. The second of these returns can be represented as follows:

In the following example, the return value of sm_ms_inquire(MOUSE_FIELD) is bitwise AND's with 0x06 in order to mask off the lowest-order bit (Shift). This lets the program determine whether Alt or Ctrl, or both, were pressed down during the last mouse click:

if ( sm_ms_inquire( MOUSE_SHIFT ))

sm_mus_time reports the number of milliseconds that elapsed since an unspecified time. You can compare this value to the value reported on previous or subsequent mouse clicks—for example, to determine whether two successive mouse clicks should be interpreted as a double mouse click.

Notes: Ordinarily, you can use the key change function to intercept double mouse click events. For more information, refer to page 47-1.

Changing the Mouse Pointer State

sm_delay_cursor sets the mouse pointer to be either the default cursor or the delay cursor, or gets the mouse pointer's current state, according to the supplied argument. It can also specify to change the cursor's state automatically, depending on whether the application is awaiting input or not.

For GUI platforms, you can set a screen's default cursor through its Pointer property. In Windows and Motif, the default cursor is an arrow. The delay cursor in Windows is an hourglass; in Motif, the delay cursor is usually a wristwatch icon. You can change Motif's default cursor through the pointerShape resource.

Because character-mode Panther does not change the mouse pointer shape, sm_delay_cursor resets the background status line message to the value of SM_WAIT or SM_READY. Note that you can turn background status messages on and off through sm_setstatus. sm_delay_cursor takes a single integer argument, one of these constants:

SM_AUTO_BUSY_CURSOR

Sets the mouse pointer to toggle automatically between the default cursor and the delay cursor, depending on whether the application is awaiting input or not. The default cursor appears whenever Panther is awaiting input.

SM_BUSY_CURSOR

Changes the mouse pointer into the delay cursor.

SM_DEFAULT_CURSOR

Restores the default cursor.

SM_SAME_CURSOR

Leaves the mouse pointer unchanged. Use this argument to get the pointer's current state.

SM_TEMP_BUSY_CURSOR

Temporarily changes the mouse pointer to the delay cursor. Panther restores the mouse pointer to the default cursor after Panther refreshes the screen.