Making Controls Easier to Use

You want to make it as easy as possible for users to understand and use your controls. Access keys, tab order, ToolTip text, and selective disabling all contribute to a more usable design.

Setting Access Keys

An access key makes it possible for a user to choose a control from anywhere in the form by pressing ALT and the key.

To specify an access key for a control

• Precede the desired letter in the Caption property for the control with a backslash and a less than sign (\<).

For example, the following property setting for the Caption of a command button makes O the access key.

\<Open

A user can choose the command button from anywhere in the form by pressing ALT+O.

To specify an access key for a text box or edit box

1. Create a label with a backslash and less than sign (\<) in front of the desired letter, such as C\<ustomer.
2. Make sure the label is the control in the tab order immediately preceding the text box or edit box you want to receive the focus.

Setting the Tab Order of Controls

The default tab order of controls on your form is the order in which you added the controls to the form.

Tip   Set the tab order of controls so that the user can easily move through your controls in a logical order.

To change the tab order of controls

1. In the Form Designer toolbar, choose Set Tab Order.
2. Double-click the box next to the control you want to have the initial focus when the form opens.
3. Click the box next to the other controls in the order you want them to be tabbed to.
4. Click anywhere outside the tab order boxes to finish.

You also can set the tab order for the objects on your form by list, depending on the setting in the Form Design tab of the Options dialog box.

You can set the selection order for the option and command buttons within a control group. To move to a control group with the keyboard, a user tabs to the first button in the control group and then uses the arrow keys to select other buttons in the group.

To change the selection order of buttons within a control group

1. In the Properties window, select the group in the Object list. A thick border indicates that the group is in edit mode.
2. Select the Form Designer window.
3. From the View menu, choose Tab Order.
4. Set the selection order as you would the tab order for controls.

Setting ToolTip Text

Each control has a ToolTipText property that makes it possible for you to specify the text displayed when the user pauses the mouse pointer over the control. Tips are especially useful for buttons with icons instead of text.

To specify ToolTip text

• In the Properties window, select the ToolTipText property and type the desired text.

The form's ShowTips property determines whether ToolTip text is displayed.

Change the Mouse Pointer Display

You can change the mouse pointer display to provide visual clues to your users about different states your application might be in.

For example, in the tsBaseForm class of the Tasmanian Traders sample application, a WaitMode method changes the mouse pointer to the default wait state cursor. Before running any code that might take a while to process, the Tasmanian Traders application passes a value of true (.T.) to the WaitMode method to change the pointer and let the user know that processing is going on. After the processing is completed, a call to WaitMode with false (.F.) restores the default mouse pointer.

* WaitMode Method of tsBaseForm class
LPARAMETERS tlWaitMode

lnMousePointer = IIF(tlWaitMode, MOUSE_HOURGLASS, MOUSE_DEFAULT)
THISFORM.MousePointer = lnMousePointer
THISFORM.SetAll('MousePointer', lnMousePointer)

If you want to change the mouse pointer to something other than one of the default pointers, set the MousePointer Property to 99 - Custom and set theMousePointer Property to your own cursor (.cur) or icon (.ico) file.

Enabling and Disabling Controls

Set a control's Enabled property to false (.F.) if the functionality of the control is not available in a given situation.

Enabling and Disabling Buttons in a Group

You can enable or disable individual option buttons or command buttons in a group by setting the Enabled property of each button to either true (.T.) or false (.F.). You also can disable or enable all the buttons in a group by setting the Enabled property of the group, as in the following line of code:

frmForm1.cmgCommandGroup1.Enabled = .T.

When you set the Enabled property of an option button group or a command button group to false (.F.), all the buttons in the group are disabled, but won't be displayed with the disabled ForeColor and BackColor. Setting the Enabled property of the group does not change the Enabled property of the individual buttons in the group. This makes it possible for you to disable a group of buttons with some of the buttons already disabled. When you enable the group, buttons that were originally disabled remain disabled.

If you want to disable all the buttons in a group so that they appear disabled, and if you don't want to preserve information about which buttons were originally disabled or enabled, you can use the SetAll method of the group, like this:

frmForm1.opgOptionGroup1.SetAll("Enabled", .F.)

Allowing Users to Drag and Drop

When you design Visual FoxPro applications, you can drag text, files, and objects from the Component Gallery, Project Manager, the Database Designer, and the Data Environment Designer to desired locations on forms and reports. The drag-and-drop features in Visual FoxPro make it possible for you to extend this ability to the user at run time.

This drag-and-drop capability extends to multiple-form operations. The user can drag text, files, and controls anywhere on the screen, including other forms.

Two types of drag and drop are now supported in Visual FoxPro: OLE drag-and-drop and control drag and drop. OLE drag-and-drop makes it possible for you to move data between other applications that support OLE drag-and-drop (such as Visual FoxPro, Visual Basic, the Windows Explorer, Microsoft Word and Excel, and so on). In a distributed Visual FoxPro application, you can move data between controls in the application, or between controls and other Window applications that support OLE drag-and-drop.

Control drag and drop makes it possible for you to drag and drop Visual FoxPro controls within your Visual FoxPro applications. Control drag and drop is also supported in earlier versions of Visual FoxPro. As the user drags a control, Visual FoxPro provides a gray outline that is the same size as the object and moves with the mouse pointer. You can override this default behavior by specifying a cursor file (.cur) for the DragIcon property of a control.

This section describes control drag and drop. For more information about OLE drag-and-drop, see OLE drag-and-drop in "Interoperability and the Internet."

To see examples of control drag and drop

1. Run Solution.app in the Visual FoxPro \Samples\Solution directory.

2. In the tree view, click Controls, and then click General.

   Note   Run time dragging of a control does not change its location automatically. You can do this, but you must program the relocation yourself, as described in the section, Causing Control Movement in a Drag-and-Drop Operation. Often, dragging is used only to indicate that some action should be performed; the control retains its original position after the user releases the mouse button.

Using the following drag-and-drop properties, events, and method, you can specify both the meaning of a drag operation and how dragging can be initiated (if at all) for any given control.

All visual controls can be dragged at run time and all controls share the properties listed in the preceding table. Forms recognize the DragDrop and DragOver events, but they don't have DragMode and DragIcon properties.

Enabling Automatic Drag Mode

To make it possible for the user to drag a control whenever the user clicks the control, set its DragMode property to 1. This enables automatic dragging of the control. When you set dragging to Automatic, dragging is always on.

Note   While an automatic drag operation is taking place, the control being dragged doesn't recognize other mouse events.

Responding When the User Drops the Object

When the user releases the mouse button after dragging a control, Visual FoxPro generates a DragDrop event. You can respond to this event in many ways. You can relocate the control at the new location (indicated by the last position of the gray outline). Remember that the control does not move automatically to the new location.

Two terms are important when discussing drag-and-drop operations — source and target.

A control becomes the target if the mouse position is within its borders when the button is released. A form is the target if the pointer is in a blank portion of the form.

The DragDrop event receives three parameters: oSource, nXCoord, and nYCoord. The parameter oSource is a reference to the control that was dropped onto the target. The parameters nXCoord and nYCoord contain the horizontal and vertical coordinates, respectively, of the mouse pointer within the target.

Because oSource is an object, you use it just as you would a control — you can refer to its properties or call one of its methods. For example, the following statements in the code associated with the DragDrop event checks to see whether the user has dropped a control on itself:

LPARAMETERS oSource, nXCoord, nYCoord
IF oSource.Name != THIS.Name
   * Take some action.
ELSE
   * Control was dropped on itself.
   * Take some other action.
ENDIF

All possible control types for oSource have a Visible property. Therefore, you can make a control invisible when it's dropped on a certain part of a form or on another control. The following line in the code associated with the DragDrop event of an Image control causes a dragged control to disappear when it's dropped on the image:

LPARAMETERS oSource, nXCoord, nYCoord
oSource.Visible = .F.

Indicating Valid Drop Zones

When you enable drag-and-drop, you can help your users by including visual clues about where a user can and cannot drop a control. The best way to do this is to change the DragIcon of the source in the code associated with the DragOver event.

The following code in the DragOver event of a control indicates to a user that the control is not a valid drop target. In this example, cOldIcon is a user-defined property of the form.

LPARAMETERS oSource, nXCoord, nYCoord, nState
DO CASE
   CASE nState = 0 && Enter
      THISFORM.cOldIcon = oSource.DragIcon
      oSource.DragIcon = "NODROP01.CUR"
   CASE nState = 1 && Leave
      oSource.DragIcon = THISFORM.cOldIcon
ENDCASE

Controlling When Dragging Starts or Stops

Visual FoxPro has a setting of Manual for the DragMode property that gives you more control than the Automatic setting. The Manual setting makes it possible for you to specify when a control can and cannot be dragged. (When DragMode is set to Automatic, the control can always be dragged as long as the setting isn't changed.)

For instance, you might want to enable dragging in response to MouseDown and MouseUp events, or in response to a keyboard or menu command. The Manual setting also makes it possible for you to recognize a MouseDown event before dragging starts, so that you can record the mouse position.

To enable dragging from code, leave DragMode in its default setting (0 - Manual). Then use the Drag method whenever you want to begin or stop dragging an object:

container.control.Drag(nAction)

If nAction is 1, the Drag method initiates dragging of the control. If nAction is 2, the control is dropped, causing a DragDrop event. The value 0 for nAction cancels the drag. The effect is similar to giving the value 2, except that no DragDrop event occurs.

Note   To enable a drag and drop operation from a list box, the best place to call the Drag method is in the code associated with the MouseMove event of the source list box, after determining that the mouse button is down. For an example, see Lmover.scx in the Visual FoxPro \Samples\Solution\Controls\Lists directory.

Causing Control Movement in a Drag-and-Drop Operation

You might want the source control to change position after the user releases the mouse button. To make a control move to the new mouse location, use the Move method. For example, the following code in the DragDrop event of a form moves the control that is dragged to the location of the drop:

LPARAMETERS oSource, nXCoord, nYCoord
oSource.Move(nXCoord, nYCoord)

This code might not produce precisely the effects you want, because the upper-left corner of the control is positioned at the mouse location. The following code positions the center of the control at the mouse location:

LPARAMETERS oSource, nXCoord, nYCoord
oSource.Move ((nXCoord – oSource.Width / 2), ;
   (nYCoord – oSource.Height / 2))

The code works best when the DragIcon property is set to a value other than the default (the gray rectangle). When the gray rectangle is being used, the user normally wants the control to move precisely into the final position of the gray rectangle. To do this, record the initial mouse position within the source control. Then use this position as an offset when the control is moved. For an example, see Ddrop.scx in the Visual FoxPro\Samples\Solution\Forms directory.

To record the initial mouse position

1. Specify manual dragging of the control.
2. Declare two form-level variables, nDragX and nDragY.
3. Turn on dragging when a MouseDown event occurs. Also, store the value of nXCoord and nYCoord in the form-level variables in this event.
4. Turn dragging off when the MouseUp event occurs.

See Also

Displaying Controls in Grid Columns | Extending Forms | Using Controls | Caption property | Properties window | Controls and Objects