4.3.13 Movers

Movers

Mover dialogs are used to select a number of items from a list of available items. This sounds like a common thing to you? Well, it is. I couldn't think of any business application I've worked on that didn't have a kind of Mover dialog. Surprisingly, the quality of these dialogs is often poor, but the classes you find in this category should put an end to this misery.

Field Mover

Class	_fieldmover
Base class	Container
Class library	_movers.vcx
Parent class	_supermover
Sample	...\Samples\Vfp98\Solution\Ffc\movers.scx
Dependencies	_base.vcx, _movers.h

The Field Mover class is a Super Mover class (see below) that's automatically populated with the field names of the current data source (see Figure 38). Using this Mover object is simple. You drop it on a form that has some kind of data source, which will be used to automatically populate the listboxes. The user then selects the fields he wants. Once he's done, you can use the GetSelections() method to query the selected fields and do what you want with them.

Figure 38. A Field Mover sample that's automatically populated with the
fields of the Orders table.

The Field Mover class has a greater number of newly defined properties and methods. However, this doesn't mean that it's harder to use. Quite the opposite is true. The AutoInit property specifies whether the class should be automatically populated on instantiation (default is .T.). You might not want this if you load your data later on. In this case, you'd have to call the InitData() method to initialize the mover. Alternatively, you can also use the GetTableData() method to initialize the Mover object. Normally, the current data source is used to populate the mover. However, you can also specify a certain data source using the CurrentAlias property.

By default, all fields are displayed in the left-hand listbox, but you can also specify to skip memo fields (SkipMemo = .T.) and to skip the general fields (SkipGeneral = .T.).

The MultiTable property is rather confusing at first. It allows specifying whether selections can come from multiple tables. At first I was under the impression that this would allow displaying fields from multiple tables in the right-hand listbox. However, this is not the case. The MultiTable property simply specifies whether the selected items listbox (the right-hand listbox) should be cleared when the left-hand listbox is repopulated. Setting this property to .T. keeps the selected items, even when the left-hand listbox is repopulated.

See below (Super Mover) for more information about other features of this listbox.

Mover

Class	_mover
Base class	Container
Class library	_movers.vcx
Parent class	_container
Sample	None
Dependencies	_base.vcx, _movers.h

The Mover foundation class is the base for all FFC mover classes. It provides a simple interface with two listboxes and two command buttons to add and remove items from the right-hand listbox (see Figure 39). The available items are displayed in the left-hand listbox. When an item is added to the right-hand listbox, it is removed from the left-hand one so the user can't select items twice.

Figure 39. The most basic mover provided by the foundation classes.

The class has special methods to populate the listboxes: InitChoices() for the left-hand listbox and InitSelections() for the right-hand one. Each of these methods expects a one-dimensional array of items passed by reference like so:

LOCAL laChoices(6,1)

laChoices(1,1) = "First Name"

laChoices(2,1) = "Last Name"

laChoices(3,1) = "Street"

laChoices(4,1) = "City"

laChoices(5,1) = "State"

laChoices(6,1) = "ZIP"

THIS.InitChoices(@laChoices)

The above code should be placed in the Init() event of the mover object. It populates the choices (left-hand) listbox. The same code would also work for the selections (right-hand) listbox. In this case, you would need to call the InitSelections() method instead. Normally, the arrays you used to populate the listboxes are copied to internal arrays that serve as the control source for each listbox. Those arrays are called aChoices(1,1) and aSelections(1,1). You could modify and read these arrays later on. If you don't want to use these arrays, you can set the UseArrays property to .F., which means that the specified items are added using the listbox's AddItem() method.

Once the user has made his selection, you need a way to somehow query the selected fields. This is provided through the GetSelections() method. Again, this method expects an array passed by reference. This array is populated with all selected items. Here's an example:

LOCAL laItems(1), lnCounter
THIS.GetSelections(@laItems)

FOR lnCounter = 1 TO Alen(laItems,1)
? laItems(lnCounter)
ENDFOR

The Mover class is a container that has a couple of member objects. The class has all the knowledge to resize and reposition all member objects according to the size of the container. However, there is no automatic mechanism that triggers this resizing algorithm. This is due to the fact that movers are typically used in dialogs that can't be resized. I recommend triggering the resizing algorithm in the Init() of the form like so:

THISFORM.oMover.SizeToContainer()

As you can see, the resizing method is called SizeToContainer(). You can also send the above message from the Resize() event of the Mover object, in case your dialog is resizable.

Sort Mover

Class	_sortmover
Base class	Container
Class library	_movers.vcx
Parent class	_mover
Sample	...\Samples\Vfp98\Solution\Ffc\movers.scx
Dependencies	_base.vcx, _movers.h

The Sort Mover is a special mover class that is automatically populated with field and tag names of a table or cursor (see Figure 40). It lets the user choose which fields to use for sorting, in what order, and whether the general sorting sequence should be ascending or descending.

Figure 40. The Sort Mover being used to re-sort the contents of the Tastrade
orders table.

This class does not provide the actual sorting logic. It merely provides a simple way to populate the Mover dialog with fields and tags from a certain data source. Populating the mover is simple. You set the data source in the CurrentAlias property and fire the UpdateMover() method like so:

THIS.CurrentAlias = "orders"

THIS.UpdateMover()

This will populate the left-hand listbox with all field names of the order table. Optionally, you can also display all the index tag names by setting the ShowTags property to .T. Index tags are displayed with a trailing asterisk (*). That's also how they appear in the selected-items array.

Like the Super Mover (see below), you can specify a maximum number of selected items in the MaxFields property. However, there is no property that allows setting the message that's displayed if the user selects more fields than allowed. You'd have to change this message through the _mover.h include file.

See above (Mover class) for general information about movers.

Super Mover

Class	_supermover
Base class	Container
Class library	_movers.vcx
Parent class	_mover
Sample	...\Samples\Vfp98\Solution\Ffc\movers.scx
Dependencies	_base.vcx, _movers.h

The Super Mover foundation class is a direct subclass of the Mover foundation class (see above). It has graphical add/remove buttons as well as "add all" and "remove all" buttons (see Figure 41).

Figure 41. An advanced Super Mover dialog.

The Super Mover also allows you to specify a maximum number of items (MaxItems property) and a message (MaxMessage property) that's displayed when the user tries to select more items than you allow.

See above (Mover class) for more information.

Table Mover

Class	_tablemover
Base class	Container
Class library	_movers.vcx
Parent class	_fieldmover
Sample	...\Samples\Vfp98\Solution\Ffc\movers.scx
Dependencies	_base.vcx, _movers.h

The Table Mover is a special kind of field mover that provides an interface to select a data source (see Figure 42). Using this object is simple. The class is intelligent enough to analyze the current data environment.

Figure 42. A Table Mover object is complex and intelligent, yet easy to use.

A couple of properties allow you to specify whether certain data source types should appear in the dialog. The AllowQuery property can be used to specify whether queries should be displayed. AllowViews does the same (you guessed it) for views. Another property can be used to influence the way views are treated: ViewNoData. If you set this property to .F., the class retrieves the view's data before it uses it. Typically you don't need to do that, so the default of this property is .T.

See above (Field Mover) for more information about this class.