Apress Pro PHP-GTK phần 5 pptx

138 CHAPTER 7 ■ DISPLAYING AND COLLECTING SIMPLE DATA

Figure 7-6. GtkEntryCompletion in action

values using a GtkEntry widget. This can lead to some very messy data input. There is no guar￾antee that the users of an application know how to spell Saskatchewan. Fortunately, you can

help users supply the correct data.

GtkEntryCompletion is an object that can be associated with a GtkEntry. It tries to match

what the user is typing to a predefined list of suggested values, as shown in Figure 7-6. Using

a GtkEntryCompletion object can help to reduce the number of errors entered by the user.

GtkEntryCompletion is a helper object, not a widget. It makes no sense to think of

a GtkEntryCompletion without an associated GtkEntry.

GtkEntryCompletion is not an end-all solution. It guides the users in the right direction

when entering text, but does not force them to pick one of the suggested values. You should

use it when there is a set of likely values for a GtkEntry field, but the set of possible values is

not finite. The data that is taken from the GtkEntry field must still be checked for invalid val￾ues or characters, especially if the data is to be inserted into a database.

GtkEntryCompletion provides a list of suggested values using a GtkListStore. We’ll take

a closer look at GtkListStore in Chapter 9. For now, you just need to know that GtkListStore is

a list of data values and is the main support behind GtkEntryCompletion.

Listing 7-6 shows the code that adds the GtkEntryCompletion to the stateEntry of

ContributorEdit.

Listing 7-6. Creating and Associating a GtkEntryCompletion Object

<?php

private function _layoutTool()

{

// ...

// Help the user out with the state by using a GtkEntryCompletion.

$stateCompletion = new GtkEntryCompletion();

$stateCompletion->set_model(self::createStateList());

$stateCompletion->set_text_column(0);

$this->stateEntry->set_completion($stateCompletion);

$stateCompletion->set_inline_completion(true);

// ...

}

6137ch07.qxd 3/14/06 2:10 PM Page 138

CHAPTER 7 ■ DISPLAYING AND COLLECTING SIMPLE DATA 139

public static function createStateList()

{

$listStore = new GtkListStore(Gtk::TYPE_STRING);

$iter = $listStore->append();

$listStore->set($iter, 0, 'Alabama');

$iter = $listStore->append();

$listStore->set($iter, 0, 'Alaska');

$iter = $listStore->append();

$listStore->set($iter, 0, 'Arizona');

$iter = $listStore->append();

$listStore->set($iter, 0, 'Arkansas');

$iter = $listStore->append();

$listStore->set($iter, 0, 'California');

$iter = $listStore->append();

$listStore->set($iter, 0, 'Colorado');

// ...

return $listStore;

}

?>

The first step, as always, is to create the object. The constructor for GtkEntryCompletion

does not take any arguments.

The next step is to set a model for the entry completion using set_model. A model is

a structured data object. It manages a set of data as a tree or list. In Listing 7-6, the data model

being used is a list. The list is created in the createStateList method. This method instantiates

a GtkListStore object and adds a value for each state or province that should be suggested.

Again, the details of how the GtkListStore object works are discussed in Chapter 9.

Once the list is created and set as the model, the entry completion is told where in the

model to look for the completion values. In Listing 7-6, there is only one column of data, so

the entry completion must look in column 0. This is done using the set_text_column method.

Finally, the entry completion is associated with the GtkEntry for the state. If the user types

the letter a in the state entry, he will see something similar to the example shown earlier in

Figure 7-6.

Setting the Number of Characters for a Match

GtkEntryCompletion performs a case-insensitive string comparison to find possible matches.

That means that if the user enters a, he will see the same list of suggestions as he would if he

had entered A.

The default behavior is to check on every character that is entered. For some lists, in which

many values begin with the same few characters, trying to come up with suggested values after

only one or two characters have been entered will likely return too many values to be useful,

and will probably slow down the application. It is possible to override the default behavior by

using set_minimum_key_length. This method changes the number of characters that must be

entered before the application tries to find a match for the entry’s value.

6137ch07.qxd 3/14/06 2:10 PM Page 139

140 CHAPTER 7 ■ DISPLAYING AND COLLECTING SIMPLE DATA

Using Inline Completion

Another default behavior of GtkEntry is to show suggestions in a pop-up window, like the one

shown in Figure 7-6. The pop-up window shows up below the entry. But you don’t need to use

a pop-up window to guide the user in the right direction. You can turn it off by passing false

to set_popup_completion. What is the point of a GtkEntryCompletion without a pop-up list of

suggestions? The user can be urged to enter certain characters by using inline completion.

You activate inline completion by passing true to set_inline_completion. For instance, if

you have ever used Microsoft Excel, you have probably seen an example of inline completion.

Inline completion automatically appends one or more characters to the entry value when at

least one matching value is found. The characters that are added are selected, so that the user

will overwrite them with the next character typed; the user can continue typing if the value is

incorrect. The characters that are added to the entry value depend on the matching items in

the list.

With a pop-up completion, comparisons are made with only what the user has entered so

far. Inline completion, on the other hand, looks ahead to see what the user could type next. For

example, if a user types a into the state entry, a pop-up window would show all states that

begin with the letter A. Inline completion has only one line to work with. The user could type

an l or an r next. Therefore, inline completion does not know which characters to append. If

the user types an l next, the inline completion can make a suggestion. The only values in the

list that begin with Al also begin with Ala. It is likely that the user is trying to enter either Alaska

or Alabama. Therefore, the inline completion will append an a to the entry. If the user types

Alab, the inline completion will find only one match and set the entry’s value to Alabama,

with the last three characters highlighted. By pressing Enter, the user will select the comple￾tion text, and the entry’s value will be set to Alabama.

■Caution If GtkEntryCompletion is set to use inline completion, the value passed to

set_minimum_key_length will be ignored. This may affect performance if the list of possible completions

is very large.

Combo Boxes

GtkEntry is a free-form text-entry tool. This means that users can enter any text they like. Of

course, the application should check the value to make sure that it not only matches some

expected value or pattern, but also that the user is not trying to do something malicious, like

perform SQL injection. As noted earlier, sometimes GtkEntry is not the best way to collect data

from users. GtkComboBox is a widget that, similar to an HTML select element, provides a list of

values from which the user can select. The user may not type in a freehand value. Using

a GtkComboBox constrains the user to a given set of possible values. In cases where valid input

values can be defined by finite set of data, GtkComboBox is a much better data-entry tool than

GtkEntry.

A combo box can show any sort of data, including images, and can show the choices as

a flat list or a hierarchical tree. However, in most cases, a combo box just shows a flat list of

strings.

6137ch07.qxd 3/14/06 2:10 PM Page 140

CHAPTER 7 ■ DISPLAYING AND COLLECTING SIMPLE DATA 141

Like GtkEntryCompletion, GtkComboBox uses a model to manage data. This means that the

list of possible values needs to be kept in a GtkListStore or a GtkTreeStore. The model that is

chosen for the combo box dictates how the list of values will be shown. If a GtkListStore is used,

the combo box will show the values as a flat list. If a GtkTreeStore is used, the list will be shown

as a hierarchical structure. Figure 7-7 shows the difference between the two model views.

Working with a GtkComboBox is the same, regardless of which model is used. Here, we will

look at using a list store and also using a combo box without a model. We’ll discuss creating

and manipulating models in Chapter 9.

Flat Text Lists

As noted, most frequently, GtkComboBox is used to show a simple, flat list of text values. Because

most combo boxes are string lists, PHP-GTK provides a few helper methods to make your life

a little easier. These methods are designed specifically for GtkComboBox widgets that show a flat

text list; they do not work with those that contain multiple levels or values that are not text

strings. What is special about this type of combo box is that PHP-GTK knows exactly what the

model looks like because PHP-GTK created it. Therefore, you do not need to manage the model.

The most important method when creating a flat text combo box is the static constructor.

GtkComboBox::new_text returns a combo box that can hold only one level of strings. The combo

box that is returned will be set up so that the other helper methods can work on it properly.

To add values, call prepend_text, append_text, or insert_text. These three methods work

only on combo boxes that have been created with the new_text constructor. PHP-GTK will

create the list item and place it properly in the GtkListStore that has been automatically

created. prepend_text and append_text add values to the beginning and end of the list, while

insert_text puts the string in a specific location. insert_text expects the position first, followed

by the string to insert. To remove a value from the list, call remove_text and pass the position

of the item that should be removed.

After the user has selected a value from the combo box, you can get the string that the

user selected by using the get_active_text method.

Listing 7-7 shows how easy it is to create a flat text combo box using new_text.

Listing 7-7. Creating a Flat Text GtkComboBox

<?php

private function _layoutTool()

{

// ...

Figure 7-7. Two types of GtkComboBox widgets: GtkListStore gives a flat list (left), and GtkTreeStore

presents a hierarchical structure (right)

6137ch07.qxd 3/14/06 2:10 PM Page 141