YelpLocationEntry

YelpLocationEntry — A location entry with history and search

Synopsis

#include <yelp.h>

                    YelpLocationEntry;
                    YelpLocationEntryClass;
enum                YelpLocationEntryFlags;
GtkWidget*          yelp_location_entry_new_with_model  (GtkTreeModel *model,
                                                         gint text_column,
                                                         gint desc_column,
                                                         gint icon_column,
                                                         gint flags_column);
void                yelp_location_entry_set_completion_model
                                                        (YelpLocationEntry *entry,
                                                         GtkTreeModel *model,
                                                         gint text_column,
                                                         gint desc_column,
                                                         gint icon_column,
                                                         gint flags_column);
void                yelp_location_entry_start_search    (YelpLocationEntry *entry);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkComboBox
                                       +----GtkComboBoxEntry
                                             +----YelpLocationEntry

Implemented Interfaces

YelpLocationEntry implements AtkImplementorIface, GtkBuildable, GtkSizeRequest, GtkCellLayout and GtkCellEditable.

Properties

  "desc-column"              gint                  : Read / Write
  "enable-search"            gboolean              : Read / Write
  "flags-column"             gint                  : Read / Write
  "icon-column"              gint                  : Read / Write

Signals

  "bookmark-clicked"                               : Run Last
  "completion-selected"                            : Run Last
  "location-selected"                              : Run Last
  "search-activated"                               : Run Last

Description

YelpLocationEntry is a GtkComboBoxEntry designed to show the current location, provide a drop-down menu of previous locations, and allow the user to perform searches.

The GtkTreeModel used by a YelpLocationEntry is expected to have at least four columns: "text-column" contains the displayed name of the location, "desc-column" contains a description for each entry, "icon-column" contains an icon name for the location, and "flags-column" contains a bit field of YelpLocationEntryFlags. These columns are specified when creating a YelpLocationEntry widget with yelp_location_entry_new_with_model().

Usually, a single row in the GtkTreeModel corresponds to a location. When a user selects a row from the drop-down menu, the icon and text for that row will be placed in the embedded text entry, and the "location-selected" signal will be emitted.

If a row has the YELP_LOCATION_ENTRY_IS_SEARCH flag set, selecting that row will not emit the "location-selected" signal. Instead, the YelpLocationEntry widget will be placed into search mode, as if by a call to yelp_location_entry_start_search().

When a row has the YELP_LOCATION_ENTRY_CAN_BOOKMARK flag set, an icon will be displayed in the secondary icon position of the embedded text entry allowing the user to bookmark the location. Clicking this icon will cause the FIXME signal to be emitted.

Details

YelpLocationEntry

typedef struct _YelpLocationEntry YelpLocationEntry;

YelpLocationEntryClass

typedef struct {
    GtkComboBoxEntryClass     parent;
} YelpLocationEntryClass;

enum YelpLocationEntryFlags

typedef enum {
    YELP_LOCATION_ENTRY_CAN_BOOKMARK  = 1 << 0,
    YELP_LOCATION_ENTRY_IS_BOOKMARKED = 1 << 1,
    YELP_LOCATION_ENTRY_IS_LOADING    = 1 << 2,
    YELP_LOCATION_ENTRY_IS_SEPARATOR  = 1 << 3,
    YELP_LOCATION_ENTRY_IS_SEARCH     = 1 << 4
} YelpLocationEntryFlags;

Flags which can be used to provide additional information about rows to be displayed by a YelpLocationEntry.

YELP_LOCATION_ENTRY_CAN_BOOKMARK

This location can be bookmarked. When a bookmarkable location is selected, the secondary icon of the embedded text entry will be a clickable bookmark icon.

YELP_LOCATION_ENTRY_IS_BOOKMARKED

This location is already bookmarked. Bookmarked locations will have an emblem in drop-down lists.

YELP_LOCATION_ENTRY_IS_LOADING

Page data for this location is still loading. The YelpLocationEntry widget will display an indeterminate progress indicator.

YELP_LOCATION_ENTRY_IS_SEPARATOR

This row should be displayed as a separator.

YELP_LOCATION_ENTRY_IS_SEARCH

Selecting this row initiates a search instead of selecting a location.

yelp_location_entry_new_with_model ()

GtkWidget*          yelp_location_entry_new_with_model  (GtkTreeModel *model,
                                                         gint text_column,
                                                         gint desc_column,
                                                         gint icon_column,
                                                         gint flags_column);

Creates a new YelpLocationEntry widget.

model :

A GtkTreeModel.

text_column :

The column in model containing the title of each entry.

desc_column :

The column in model containing the description of each entry.

icon_column :

The column in model containing the icon name of each entry.

flags_column :

The column in model containing YelpLocationEntryFlags.

Returns :

A new YelpLocationEntry.

yelp_location_entry_set_completion_model ()

void                yelp_location_entry_set_completion_model
                                                        (YelpLocationEntry *entry,
                                                         GtkTreeModel *model,
                                                         gint text_column,
                                                         gint desc_column,
                                                         gint icon_column,
                                                         gint flags_column);

yelp_location_entry_start_search ()

void                yelp_location_entry_start_search    (YelpLocationEntry *entry);

Puts entry into search mode. This focuses the entry and clears its text contents. When the user activates the search, the "search-activated" signal will be emitted.

entry :

A YelpLocationEntry.

Property Details

The "desc-column" property

  "desc-column"              gint                  : Read / Write

The column in the GtkTreeModel containing a description for each row.

Allowed values: >= G_MAXULONG

Default value: -1


The "enable-search" property

  "enable-search"            gboolean              : Read / Write

Whether the location entry can act as a search entry. If search is not enabled, the user will not be able to initiate a search by clicking in the embedded text entry or selecting a search row in the drop-down menu.

Default value: TRUE


The "flags-column" property

  "flags-column"             gint                  : Read / Write

The column in the GtkTreeModel containing YelpLocationEntryFlags flags for each row.

Allowed values: >= G_MAXULONG

Default value: -1


The "icon-column" property

  "icon-column"              gint                  : Read / Write

The column in the GtkTreeModel containing an icon name for each row. This must be a name that can be looked up through GtkIconTheme.

Allowed values: >= G_MAXULONG

Default value: -1

Signal Details

The "bookmark-clicked" signal

void                user_function                      (YelpLocationEntry *widget,
                                                        gpointer           user_data)      : Run Last

This signal will be emitted whenever a user clicks the bookmark icon embedded in the location entry.

widget :

The YelpLocationEntry for which the signal was emitted.

user_data :

User data set when the handler was connected.

user_data :

user data set when the signal handler was connected.

The "completion-selected" signal

void                user_function                      (YelpLocationEntry *widget,
                                                        GtkTreeModel      *model,
                                                        GtkTreeIter       *iter,
                                                        gpointer           user_data)      : Run Last

This signal will be emitted whenever a user selects an entry in the completion drop-down while typing.

widget :

The YelpLocationEntry for which the signal was emitted.

model :

The GtkTreeModel contianing the completion.

iter :

A GtkTreeIter positioned at the completion.

user_data :

User data set when the handler was connected.

user_data :

user data set when the signal handler was connected.

The "location-selected" signal

void                user_function                      (YelpLocationEntry *widget,
                                                        gpointer           user_data)      : Run Last

This signal will be emitted whenever a user selects a normal row from the drop-down menu. Note that if a row has the flag YELP_LOCATION_ENTRY_IS_SEARCH, clicking the row will cause widget to enter search mode, and this signal will not be emitted.

widget :

The YelpLocationEntry for which the signal was emitted.

user_data :

User data set when the handler was connected.

user_data :

user data set when the signal handler was connected.

The "search-activated" signal

void                user_function                      (YelpLocationEntry *widget,
                                                        gchar             *text,
                                                        gpointer           user_data)      : Run Last

This signal will be emitted whenever the user activates a search, generally by pressing Enter in the embedded text entry while widget is in search mode.

widget :

The YelpLocationEntry for which the signal was emitted.

text :

The search text.

user_data :

User data set when the handler was connected.

user_data :

user data set when the signal handler was connected.