WnckTasklist: Libwnck Reference Manual

## WnckTasklist WnckTasklist — a tasklist widget, showing the list of windows as a list of buttons. |

## Stability Level

Unstable, unless otherwise indicated

## Functions

GtkWidget * | wnck_tasklist_new ()
GtkWidget * | wnck_tasklist_new_with_handle ()
const int * | wnck_tasklist_get_size_hint_list ()
void | wnck_tasklist_set_grouping ()
void | wnck_tasklist_set_switch_workspace_on_unminimize ()
void | wnck_tasklist_set_middle_click_close ()
void | wnck_tasklist_set_grouping_limit ()
void | wnck_tasklist_set_include_all_workspaces ()
void | wnck_tasklist_set_button_relief ()
void | wnck_tasklist_set_orientation ()
void | wnck_tasklist_set_scroll_enabled ()
gboolean | wnck_tasklist_get_scroll_enabled ()
void | wnck_tasklist_set_tooltips_enabled ()
gboolean | wnck_tasklist_get_tooltips_enabled ()
GdkPixbuf * | (*WnckLoadIconFunction) ()
void | wnck_tasklist_set_icon_loader ()

## Properties

WnckHandle * | handle | Read / Write / Construct Only
gboolean | tooltips-enabled | Read / Write

## Signals

void | task-enter-notify | Run Last
void | task-leave-notify | Run Last

## Types and Values

struct | WnckTasklist
enum | WnckTasklistGroupingType

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── WnckTasklist

## Implemented Interfaces

WnckTasklist implements AtkImplementorIface and GtkBuildable.

## Description

The WnckTasklist represents client windows on a screen as a list of buttons labelled with the window titles and icons. Pressing a button can activate or minimize the represented window, and other typical actions are available through a popup menu. Windows needing attention can also be distinguished by a fade effect on the buttons representing them, to help attract the user's attention.

The behavior of the WnckTasklist can be customized in various ways, like grouping multiple windows of the same application in one button (see `wnck_tasklist_set_grouping()` and `wnck_tasklist_set_grouping_limit()`), or showing windows from all workspaces (see `wnck_tasklist_set_include_all_workspaces()`). The fade effect for windows needing attention can be controlled by various style properties like “fade-max-loops” and “fade-opacity”.

The tasklist also acts as iconification destination. If there are multiple WnckTasklist or other applications setting the iconification destination for windows, the iconification destinations might not be consistent among windows and it is not possible to determine which WnckTasklist (or which other application) owns this propriety.

## Functions

### wnck_tasklist_new ()

    GtkWidget *
    wnck_tasklist_new (void);

`wnck_tasklist_new` is deprecated and should not be used in newly-written code.

Creates a new WnckTasklist. The WnckTasklist will list WnckWindow of the WnckScreen it is on.

#### Returns

a newly created WnckTasklist.

### wnck_tasklist_new_with_handle ()

    GtkWidget *
    wnck_tasklist_new_with_handle (WnckHandle *handle);

Creates a new WnckTasklist. The WnckTasklist will list WnckWindow of the WnckScreen it is on.

#### Parameters

handle | a WnckHandle |

#### Returns

a newly created WnckTasklist.

### wnck_tasklist_get_size_hint_list ()

    const int *
    wnck_tasklist_get_size_hint_list (WnckTasklist *tasklist,
                                      int *n_elements);

`wnck_tasklist_get_size_hint_list` has been deprecated since version 3.42 and should not be used in newly-written code.

Use minimum and natural size instead.

Since a WnckTasklist does not have a fixed size (WnckWindow can be grouped when needed, for example), the standard size request mechanism in GTK+ is not enough to announce what sizes can be used by `tasklist` . The size hints mechanism is a solution for this. See `panel_applet_set_size_hints()` for more information.

#### Parameters

tasklist | a WnckTasklist. |
n_elements | return location for the number of elements in the array returned by this function. This number should always be pair. |

#### Returns

a list of size hints that can be used to allocate an appropriate size for `tasklist` .

### wnck_tasklist_set_grouping ()

    void
    wnck_tasklist_set_grouping (WnckTasklist *tasklist,
                                WnckTasklistGroupingType grouping);

Sets the grouping policy for `tasklist` to `grouping` .

#### Parameters

tasklist | a WnckTasklist. |
grouping | a grouping policy. |

### wnck_tasklist_set_switch_workspace_on_unminimize ()

    void
    wnck_tasklist_set_switch_workspace_on_unminimize
                                   (WnckTasklist *tasklist,
                                    gboolean switch_workspace_on_unminimize);

Sets `tasklist` to activate or not the WnckWorkspace a WnckWindow is on when unminimizing it, according to `switch_workspace_on_unminimize` .

FIXME: does it still work?

#### Parameters

tasklist | a WnckTasklist. |
switch_workspace_on_unminimize | whether to activate the WnckWorkspace a WnckWindow is on when unminimizing it. |

### wnck_tasklist_set_middle_click_close ()

    void
    wnck_tasklist_set_middle_click_close (WnckTasklist *tasklist,
                                          gboolean middle_click_close);

Sets `tasklist` to close windows with mouse middle click on button, according to `middle_click_close` .

#### Parameters

tasklist | a WnckTasklist. |
middle_click_close | whether to close windows with middle click on button. |

Since: 3.4.6

### wnck_tasklist_set_grouping_limit ()

    void
    wnck_tasklist_set_grouping_limit (WnckTasklist *tasklist,
                                      gint limit);

Sets the maximum size of buttons in `tasklist` before `tasklist` tries to group WnckWindow in the same WnckApplication in only one button. This limit is valid only when the grouping policy of `tasklist` is `WNCK_TASKLIST_AUTO_GROUP`.

#### Parameters

tasklist | a WnckTasklist. |
limit | a size in pixels. |

### wnck_tasklist_set_include_all_workspaces ()

    void
    wnck_tasklist_set_include_all_workspaces
                                   (WnckTasklist *tasklist,
                                    gboolean include_all_workspaces);

Sets `tasklist` to display WnckWindow from all WnckWorkspace or not, according to `include_all_workspaces` .

Note that if the active WnckWorkspace has a viewport and if `include_all_workspaces` is `FALSE`, then only the WnckWindow visible in the viewport are displayed in `tasklist` . The rationale for this is that the viewport is generally used to implement workspace-like behavior. A side-effect of this is that, when using multiple WnckWorkspace with viewport, it is not possible to show all WnckWindow from a WnckWorkspace (even those that are not visible in the viewport) in `tasklist` without showing all WnckWindow from all WnckWorkspace.

#### Parameters

tasklist | a WnckTasklist. |
include_all_workspaces | whether to display WnckWindow from all WnckWorkspace in `tasklist` . |

### wnck_tasklist_set_button_relief ()

    void
    wnck_tasklist_set_button_relief (WnckTasklist *tasklist,
                                     GtkReliefStyle relief);

Sets the relief type of the buttons in `tasklist` to `relief` . The main use of this function is proper integration of WnckTasklist in panels with non-system backgrounds.

#### Parameters

tasklist | a WnckTasklist. |
relief | a relief type. |

Since: 2.12

### wnck_tasklist_set_orientation ()

    void
    wnck_tasklist_set_orientation (WnckTasklist *tasklist,
                                   GtkOrientation orient);

Set the orientation of the `tasklist` to match `orient` . This function can be used to integrate a WnckTasklist in vertical panels.

#### Parameters

tasklist | a WnckTasklist. |
orient | a GtkOrientation. |

Since: 3.4.6

### wnck_tasklist_set_scroll_enabled ()

    void
    wnck_tasklist_set_scroll_enabled (WnckTasklist *tasklist,
                                      gboolean scroll_enabled);

Sets the scroll behavior of the `tasklist` . When set to `TRUE`, a scroll event over the tasklist will change the current window accordingly.

#### Parameters

tasklist | a WnckTasklist. |
scroll_enabled | a boolean. |

Since: 3.24.0

### wnck_tasklist_get_scroll_enabled ()

    gboolean
    wnck_tasklist_get_scroll_enabled (WnckTasklist *tasklist);

Gets the scroll behavior of the `tasklist` .

#### Parameters

tasklist | a WnckTasklist. |

Since: 3.24.0

### wnck_tasklist_set_tooltips_enabled ()

    void
    wnck_tasklist_set_tooltips_enabled (WnckTasklist *self,
                                        gboolean tooltips_enabled);

Sets whether tooltips are enabled on the `tasklist` .

#### Parameters

self | a WnckTasklist. |
tooltips_enabled | a boolean. |

Since: 43.1

### wnck_tasklist_get_tooltips_enabled ()

    gboolean
    wnck_tasklist_get_tooltips_enabled (WnckTasklist *self);

Returns whether tooltips are enabled on the `tasklist` .

#### Parameters

self | a WnckTasklist. |

Since: 43.1

### WnckLoadIconFunction ()

    GdkPixbuf *
    (*WnckLoadIconFunction) (const char *icon_name,
                             int size,
                             unsigned int flags,
                             void *data);

Specifies the type of function passed to `wnck_tasklist_set_icon_loader()`.

#### Parameters

icon_name | an icon name as in the Icon field in a .desktop file for the icon to load. |
size | the desired icon size. |
flags | not defined to do anything yet. |
data | data passed to the function, set when the WnckLoadIconFunction has been set for the WnckTasklist. |

#### Returns

it should return a `GdkPixbuf` of `icon_name` at size `size` , or `NULL` if no icon for `icon_name` at size `size` could be loaded.

Since: 2.2

### wnck_tasklist_set_icon_loader ()

    void
    wnck_tasklist_set_icon_loader (WnckTasklist *tasklist,
                                   WnckLoadIconFunction load_icon_func,
                                   void *data,
                                   GDestroyNotify free_data_func);

`wnck_tasklist_set_icon_loader` has been deprecated since version 43.2 and should not be used in newly-written code.

Icon loader is included in libwnck. load_icon_func will be ignored.

Sets a function to be used for loading icons.

#### Parameters

tasklist | a WnckTasklist |
load_icon_func | icon loader function |
data | data for icon loader function |
free_data_func | function to free the data |

Since: 2.2

## Types and Values

### struct WnckTasklist

    struct WnckTasklist;

The WnckTasklist struct contains only private fields and should not be directly accessed.

### enum WnckTasklistGroupingType

Type defining the policy of the WnckTasklist for grouping multiple WnckWindow of the same WnckApplication.

#### Members

WNCK_TASKLIST_NEVER_GROUP | never group multiple WnckWindow of the same WnckApplication. |
WNCK_TASKLIST_AUTO_GROUP | group multiple WnckWindow of the same WnckApplication for some WnckApplication, when there is not enough place to have a good-looking list of all WnckWindow. |
WNCK_TASKLIST_ALWAYS_GROUP | always group multiple WnckWindow of the same WnckApplication, for all WnckApplication. |

## Property Details

### The `“handle”` property

      “handle”                   WnckHandle *

handle.

Owner: WnckTasklist

Flags: Read / Write / Construct Only

### The `“tooltips-enabled”` property

      “tooltips-enabled”         gboolean

tooltips-enabled.

Owner: WnckTasklist

Flags: Read / Write

Default value: TRUE

## Signal Details

### The `“task-enter-notify”` signal

    void
    user_function (WnckTasklist *tasklist,
                   gpointer      windows,
                   gpointer      user_data)

Emitted when the task is entered.

#### Parameters

tasklist | the WnckTasklist which emitted the signal. |
windows | the GList with all the WnckWindow belonging to the task. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“task-leave-notify”` signal

    void
    user_function (WnckTasklist *tasklist,
                   gpointer      windows,
                   gpointer      user_data)

Emitted when the task is entered.

#### Parameters

tasklist | the WnckTasklist which emitted the signal. |
windows | the GList with all the WnckWindow belonging to the task. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

WnckScreen, WnckSelector