MatewnckTasklist

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

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libmatewnck/libmatewnck.h>

    struct              MatewnckTasklist;
    GtkWidget *         matewnck_tasklist_new               (MatewnckScreen *screen);
    void                matewnck_tasklist_set_screen        (MatewnckTasklist *tasklist,
                                                             MatewnckScreen *screen);
    enum                MatewnckTasklistGroupingType;
    void                matewnck_tasklist_set_grouping      (MatewnckTasklist *tasklist,
                                                             MatewnckTasklistGroupingType grouping);
    void                matewnck_tasklist_set_grouping_limit
                                                            (MatewnckTasklist *tasklist,
                                                             gint limit);
    void                matewnck_tasklist_set_include_all_workspaces
                                                            (MatewnckTasklist *tasklist,
                                                             gboolean include_all_workspaces);
    void                matewnck_tasklist_set_switch_workspace_on_unminimize
                                                            (MatewnckTasklist *tasklist,
                                                             gboolean switch_workspace_on_unminimize);
    void                matewnck_tasklist_set_button_relief (MatewnckTasklist *tasklist,
                                                             GtkReliefStyle relief);
    gint                matewnck_tasklist_get_minimum_width (MatewnckTasklist *tasklist);
    void                matewnck_tasklist_set_minimum_width (MatewnckTasklist *tasklist,
                                                             gint size);
    gint                matewnck_tasklist_get_minimum_height
                                                            (MatewnckTasklist *tasklist);
    void                matewnck_tasklist_set_minimum_height
                                                            (MatewnckTasklist *tasklist,
                                                             gint size);
    GdkPixbuf *         (*MatewnckLoadIconFunction)         (const char *icon_name,
                                                             int size,
                                                             unsigned int flags,
                                                             void *data);
    void                matewnck_tasklist_set_icon_loader   (MatewnckTasklist *tasklist,
                                                             MatewnckLoadIconFunction load_icon_func,
                                                             void *data,
                                                             GDestroyNotify free_data_func);
    const int *         matewnck_tasklist_get_size_hint_list
                                                            (MatewnckTasklist *tasklist,
                                                             int *n_elements);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----MatewnckTasklist

## Implemented Interfaces

MatewnckTasklist implements AtkImplementorIface and GtkBuildable.

## Style Properties

      "fade-loop-time"           gfloat                : Read
      "fade-max-loops"           gint                  : Read
      "fade-opacity"             gfloat                : Read
      "fade-overlay-rect"        gboolean              : Read

## Description

The MatewnckTasklist 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 MatewnckTasklist can be customized in various ways, like grouping multiple windows of the same application in one button (see `matewnck_tasklist_set_grouping()` and `matewnck_tasklist_set_grouping_limit()`), or showing windows from all workspaces (see `matewnck_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 MatewnckTasklist 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 MatewnckTasklist (or which other application) owns this propriety.

## Details

### struct MatewnckTasklist

    struct MatewnckTasklist;

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

### matewnck_tasklist_new ()

    GtkWidget *         matewnck_tasklist_new               (MatewnckScreen *screen);

Creates a new MatewnckTasklist. The MatewnckTasklist will list MatewnckWindow of the MatewnckScreen it is on.

`screen` : | deprecated argument, can be `NULL`.
Returns : | a newly created MatewnckTasklist.

### matewnck_tasklist_set_screen ()

    void                matewnck_tasklist_set_screen        (MatewnckTasklist *tasklist,
                                                             MatewnckScreen *screen);

### Warning

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

Does nothing.

`tasklist` : | a MatewnckTasklist.
`screen` : | a MatewnckScreen.

Since 2.2

### enum MatewnckTasklistGroupingType

    typedef enum {
      MATEWNCK_TASKLIST_NEVER_GROUP,
      MATEWNCK_TASKLIST_AUTO_GROUP,
      MATEWNCK_TASKLIST_ALWAYS_GROUP
    } MatewnckTasklistGroupingType;

Type defining the policy of the MatewnckTasklist for grouping multiple MatewnckWindow of the same MatewnckApplication.

`MATEWNCK_TASKLIST_NEVER_GROUP` | never group multiple MatewnckWindow of the same MatewnckApplication.
`MATEWNCK_TASKLIST_AUTO_GROUP` | group multiple MatewnckWindow of the same MatewnckApplication for some MatewnckApplication, when there is not enough place to have a good-looking list of all MatewnckWindow.
`MATEWNCK_TASKLIST_ALWAYS_GROUP` | always group multiple MatewnckWindow of the same MatewnckApplication, for all MatewnckApplication.

### matewnck_tasklist_set_grouping ()

    void                matewnck_tasklist_set_grouping      (MatewnckTasklist *tasklist,
                                                             MatewnckTasklistGroupingType grouping);

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

`tasklist` : | a MatewnckTasklist.
`grouping` : | a grouping policy.

### matewnck_tasklist_set_grouping_limit ()

    void                matewnck_tasklist_set_grouping_limit
                                                            (MatewnckTasklist *tasklist,
                                                             gint limit);

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

`tasklist` : | a MatewnckTasklist.
`limit` : | a size in pixels.

### matewnck_tasklist_set_include_all_workspaces ()

    void                matewnck_tasklist_set_include_all_workspaces
                                                            (MatewnckTasklist *tasklist,
                                                             gboolean include_all_workspaces);

Sets `tasklist` to display MatewnckWindow from all MatewnckWorkspace or not, according to `include_all_workspaces`.

Note that if the active MatewnckWorkspace has a viewport and if `include_all_workspaces` is `FALSE`, then only the MatewnckWindow 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 MatewnckWorkspace with viewport, it is not possible to show all MatewnckWindow from a MatewnckWorkspace (even those that are not visible in the viewport) in `tasklist` without showing all MatewnckWindow from all MatewnckWorkspace.

`tasklist` : | a MatewnckTasklist.
`include_all_workspaces` : | whether to display MatewnckWindow from all MatewnckWorkspace in `tasklist`.

### matewnck_tasklist_set_switch_workspace_on_unminimize ()

    void                matewnck_tasklist_set_switch_workspace_on_unminimize
                                                            (MatewnckTasklist *tasklist,
                                                             gboolean switch_workspace_on_unminimize);

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

FIXME: does it still work?

`tasklist` : | a MatewnckTasklist.
`switch_workspace_on_unminimize` : | whether to activate the MatewnckWorkspace a MatewnckWindow is on when unminimizing it.

### matewnck_tasklist_set_button_relief ()

    void                matewnck_tasklist_set_button_relief (MatewnckTasklist *tasklist,
                                                             GtkReliefStyle relief);

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

`tasklist` : | a MatewnckTasklist.
`relief` : | a relief type.

Since 2.12

### matewnck_tasklist_get_minimum_width ()

    gint                matewnck_tasklist_get_minimum_width (MatewnckTasklist *tasklist);

### Warning

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

Returns -1.

`tasklist` : | a MatewnckTasklist.
Returns : | -1.

### matewnck_tasklist_set_minimum_width ()

    void                matewnck_tasklist_set_minimum_width (MatewnckTasklist *tasklist,
                                                             gint size);

### Warning

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

Does nothing.

`tasklist` : | a MatewnckTasklist.
`size` : | a minimum width in pixels.

### matewnck_tasklist_get_minimum_height ()

    gint                matewnck_tasklist_get_minimum_height
                                                            (MatewnckTasklist *tasklist);

### Warning

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

Returns -1.

`tasklist` : | a MatewnckTasklist.
Returns : | -1.

### matewnck_tasklist_set_minimum_height ()

    void                matewnck_tasklist_set_minimum_height
                                                            (MatewnckTasklist *tasklist,
                                                             gint size);

### Warning

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

Does nothing.

`tasklist` : | a MatewnckTasklist.
`size` : | a minimum height in pixels.

### MatewnckLoadIconFunction ()

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

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

`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 MatewnckLoadIconFunction has been set for the MatewnckTasklist.
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

### matewnck_tasklist_set_icon_loader ()

    void                matewnck_tasklist_set_icon_loader   (MatewnckTasklist *tasklist,
                                                             MatewnckLoadIconFunction load_icon_func,
                                                             void *data,
                                                             GDestroyNotify free_data_func);

Sets a function to be used for loading icons.

`tasklist` : | a MatewnckTasklist
`load_icon_func` : | icon loader function
`data` : | data for icon loader function
`free_data_func` : | function to free the data

Since 2.2

### matewnck_tasklist_get_size_hint_list ()

    const int *         matewnck_tasklist_get_size_hint_list
                                                            (MatewnckTasklist *tasklist,
                                                             int *n_elements);

Since a MatewnckTasklist does not have a fixed size (MatewnckWindow 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 `mate_panel_applet_set_size_hints()` for more information.

`tasklist` : | a MatewnckTasklist.
`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`.

## Style Property Details

### The `"fade-loop-time"` style property

      "fade-loop-time"           gfloat                : Read

When a window needs attention, a fade effect is drawn on the button representing the window. This property controls the time one loop of this fade effect takes, in seconds.

Allowed values: [0.2,10]

Default value: 3

Since 2.16

### The `"fade-max-loops"` style property

      "fade-max-loops"           gint                  : Read

When a window needs attention, a fade effect is drawn on the button representing the window. This property controls the number of loops for this fade effect. 0 means the button will only fade to the final color.

Allowed values: [0,50]

Default value: 5

Since 2.20

### The `"fade-opacity"` style property

      "fade-opacity"             gfloat                : Read

When a window needs attention, a fade effect is drawn on the button representing the window. This property controls the final opacity that will be reached by the fade effect.

Allowed values: [0,1]

Default value: 0.8

Since 2.16

### The `"fade-overlay-rect"` style property

      "fade-overlay-rect"        gboolean              : Read

When a window needs attention, a fade effect is drawn on the button representing the window. Set this property to `TRUE` to enable a compatibility mode for pixbuf engine themes that cannot react to color changes. If enabled, a rectangle with the correct color will be drawn on top of the button.

Default value: TRUE

Since 2.16

## See Also

MatewnckScreen, MatewnckSelector