WnckTasklist

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

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libwnck/libwnck.h>

struct              WnckTasklist;
GtkWidget *         wnck_tasklist_new                   (WnckScreen *screen);
void                wnck_tasklist_set_screen            (WnckTasklist *tasklist,
                                                         WnckScreen *screen);
enum                WnckTasklistGroupingType;
void                wnck_tasklist_set_grouping          (WnckTasklist *tasklist,
                                                         WnckTasklistGroupingType grouping);
void                wnck_tasklist_set_grouping_limit    (WnckTasklist *tasklist,
                                                         gint limit);
void                wnck_tasklist_set_include_all_workspaces
                                                        (WnckTasklist *tasklist,
                                                         gboolean include_all_workspaces);
void                wnck_tasklist_set_switch_workspace_on_unminimize
                                                        (WnckTasklist *tasklist,
                                                         gboolean switch_workspace_on_unminimize);
void                wnck_tasklist_set_button_relief     (WnckTasklist *tasklist,
                                                         GtkReliefStyle relief);
gint                wnck_tasklist_get_minimum_width     (WnckTasklist *tasklist);
void                wnck_tasklist_set_minimum_width     (WnckTasklist *tasklist,
                                                         gint size);
gint                wnck_tasklist_get_minimum_height    (WnckTasklist *tasklist);
void                wnck_tasklist_set_minimum_height    (WnckTasklist *tasklist,
                                                         gint size);
GdkPixbuf *         (*WnckLoadIconFunction)             (const char *icon_name,
                                                         int size,
                                                         unsigned int flags,
                                                         void *data);
void                wnck_tasklist_set_icon_loader       (WnckTasklist *tasklist,
                                                         WnckLoadIconFunction load_icon_func,
                                                         void *data,
                                                         GDestroyNotify free_data_func);
const int *         wnck_tasklist_get_size_hint_list    (WnckTasklist *tasklist,
                                                         int *n_elements);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----WnckTasklist

Implemented Interfaces

WnckTasklist 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 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.

Details

struct WnckTasklist

struct WnckTasklist;

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

wnck_tasklist_new ()

GtkWidget *         wnck_tasklist_new                   (WnckScreen *screen);

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

screen :

 deprecated argument, can be NULL.

Returns :

 a newly created WnckTasklist.

wnck_tasklist_set_screen ()

void                wnck_tasklist_set_screen            (WnckTasklist *tasklist,
                                                         WnckScreen *screen);

Warning

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

Does nothing.

tasklist :

 a WnckTasklist.

screen :

 a WnckScreen.

Since 2.2

enum WnckTasklistGroupingType

typedef enum {
  WNCK_TASKLIST_NEVER_GROUP,
  WNCK_TASKLIST_AUTO_GROUP,
  WNCK_TASKLIST_ALWAYS_GROUP
} WnckTasklistGroupingType;

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

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.

wnck_tasklist_set_grouping ()

void                wnck_tasklist_set_grouping          (WnckTasklist *tasklist,
                                                         WnckTasklistGroupingType grouping);

Sets the grouping policy for tasklist to grouping.

tasklist :

 a WnckTasklist.

grouping :

 a grouping policy.

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.

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.

tasklist :

 a WnckTasklist.

include_all_workspaces :

 whether to display WnckWindow from all WnckWorkspace in tasklist.

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?

tasklist :

 a WnckTasklist.

switch_workspace_on_unminimize :

 whether to activate the WnckWorkspace a WnckWindow is on when unminimizing it.

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.

tasklist :

 a WnckTasklist.

relief :

 a relief type.

Since 2.12

wnck_tasklist_get_minimum_width ()

gint                wnck_tasklist_get_minimum_width     (WnckTasklist *tasklist);

Warning

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

Returns -1.

tasklist :

 a WnckTasklist.

Returns :

 -1.

wnck_tasklist_set_minimum_width ()

void                wnck_tasklist_set_minimum_width     (WnckTasklist *tasklist,
                                                         gint size);

Warning

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

Does nothing.

tasklist :

 a WnckTasklist.

size :

 a minimum width in pixels.

wnck_tasklist_get_minimum_height ()

gint                wnck_tasklist_get_minimum_height    (WnckTasklist *tasklist);

Warning

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

Returns -1.

tasklist :

 a WnckTasklist.

Returns :

 -1.

wnck_tasklist_set_minimum_height ()

void                wnck_tasklist_set_minimum_height    (WnckTasklist *tasklist,
                                                         gint size);

Warning

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

Does nothing.

tasklist :

 a WnckTasklist.

size :

 a minimum height in pixels.

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().

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);

Sets a function to be used for loading icons.

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

wnck_tasklist_get_size_hint_list ()

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

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.

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.

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

WnckScreen, WnckSelector
Generated by GTK-Doc V1.17.1