PolKitGnomeToggleAction

## PolKitGnomeToggleAction PolKitGnomeToggleAction — A GtkAction that can be toggled to obtain and give up PolicyKit authorizations. |

## Functions

PolKitGnomeToggleAction * | polkit_gnome_toggle_action_new ()
PolKitGnomeToggleAction * | polkit_gnome_toggle_action_new_default ()
GtkWidget * | polkit_gnome_toggle_action_create_toggle_button ()

## Properties

gchar * | auth-underway-icon-name | Read / Write
gchar * | auth-underway-label | Read / Write
gboolean | auth-underway-sensitive | Read / Write
gchar * | auth-underway-short-label | Read / Write
gchar * | auth-underway-tooltip | Read / Write
gboolean | auth-underway-visible | Read / Write

## Signals

void | toggled | Run Last

## Types and Values

| PolKitGnomeToggleActionPrivate
struct | PolKitGnomeToggleAction

## Object Hierarchy

        GObject
        ╰── GtkAction
            ╰── PolKitGnomeAction
                ╰── PolKitGnomeToggleAction

## Implemented Interfaces

PolKitGnomeToggleAction implements GtkBuildable.

## Description

For an example of how to use this class, see the documentation for PolKitGnomeAction.

## Functions

### polkit_gnome_toggle_action_new ()

    PolKitGnomeToggleAction *
    polkit_gnome_toggle_action_new (const gchar *name);

Creates a new PolKitGnomeToggleAction object. The typical use for this function is for specialized use where `polkit_gnome_toggle_action_new_default()` does not meet the needs of the application.

If the 'polkit-toggle_action' property is NULL the behavior is similar to as if a PolKitAction returned POLKIT_RESULT_YES.

#### Parameters

name | A unique name for the toggle_action |

#### Returns

a new PolKitGnomeToggleAction or NULL if error is set

### polkit_gnome_toggle_action_new_default ()

    PolKitGnomeToggleAction *
    polkit_gnome_toggle_action_new_default
                                   (const gchar *name,
                                    PolKitAction *polkit_action,
                                    const gchar *locked_label,
                                    const gchar *unlocked_label);

Creates a new PolKitGnomeToggleAction object with the default behavior for a given PolKitAction object. The toggle represents whether the user is authorized for the given PolKitAction. If the user is not authorized, clicking on a proxy widget (if it's sensitive) will cause an authentication dialog to appear. If the user is authorized, clicking on a proxy widget will cause all authorizations to be given up (aka revoked). The ::toggled signal is only emitted when such transitions occur. Thus, the user of this class will never have to deal with bringing up authentication dialogs; it's all handled behind the scenes.

As such, the typical use case for this action is an UI where the user is encouraged to give up authorizations.

There's also support for the corner case where the user is authorized because of implicit authorizations. In this case, toggling the action will "grant" a negative authorization for the user. By toggling the action again, the negative authorization will be revoked.

Default behavior is defined as having the icon_name be 'security-medium' by default except for the YES PolicyKit answer where it's set to 'security-low'. No tooltips are set. The label and short-label will be 'locked_label' everywhere except in the YES state where it's set to 'unlocked-label'. When authentication is underway, the label will be "Authenticating..." and icon_name is untouched. If the PolicyKit answer is NO, sensitivity is set to FALSE. Visibility is always set to TRUE.

The caller can always modify individual aspects of the toggle_action after creation, e.g. change the tooltip for the no, auth and yes states; see the parent class PolKitGnomeAction. In addition to the properties in the parent class, this subclass sports six new properties, "auth-underway-*" to control the look of proxy widgets when authentication is underway.

If the given polkit_toggle_action is NULL the behavior is similar to as if a PolKitAction returned POLKIT_RESULT_YES.

#### Parameters

name | A unique name for the toggle_action |
polkit_action | the PolKitAction to track |
locked_label | The label to show when the user do not possess the authorization, e.g. "Click to make changes" |
unlocked_label | The label to show when the user does posses the authorization; e.g. "Click to prevent changes" |

#### Returns

a new PolKitGnomeToggleAction or NULL if error is set

### polkit_gnome_toggle_action_create_toggle_button ()

    GtkWidget *
    polkit_gnome_toggle_action_create_toggle_button
                                   (PolKitGnomeToggleAction *action);

Create a toggle button for the given action that displays the label, tooltip and icon_name corresponding to whether the state, according to PolicyKit, is no, auth or yes.

#### Parameters

action | The PolKitGnomeToggleAction object |

#### Returns

A GtkToggleButton instance connected to the action

## Types and Values

### PolKitGnomeToggleActionPrivate

    typedef struct _PolKitGnomeToggleActionPrivate PolKitGnomeToggleActionPrivate;

### struct PolKitGnomeToggleAction

    struct PolKitGnomeToggleAction;

The PolKitGnomeToggleAction struct contains only private data members and should not be accessed directly.

## Property Details

### The `“auth-underway-icon-name”` property

      “auth-underway-icon-name”  gchar *

When authentication is underway, use this icon-name.

Flags: Read / Write

Default value: NULL

### The `“auth-underway-label”` property

      “auth-underway-label”      gchar *

When authentication is underway, use this label.

Flags: Read / Write

Default value: NULL

### The `“auth-underway-sensitive”` property

      “auth-underway-sensitive”  gboolean

When authentication is underway, whether the action will be sensitive.

Flags: Read / Write

Default value: TRUE

### The `“auth-underway-short-label”` property

      “auth-underway-short-label” gchar *

When authentication is underway, use this short-label.

Flags: Read / Write

Default value: NULL

### The `“auth-underway-tooltip”` property

      “auth-underway-tooltip”    gchar *

When authentication is underway, use this tooltip.

Flags: Read / Write

Default value: NULL

### The `“auth-underway-visible”` property

      “auth-underway-visible”    gboolean

When authentication is underway, whether the action will be visible.

Flags: Read / Write

Default value: TRUE

## Signal Details

### The `“toggled”` signal

    void
    user_function (PolKitGnomeToggleAction *toggle_action,
                   gpointer                 user_data)

The ::toggled signal is emitted when the button is toggled.

#### Parameters

toggle_action | the object |
user_data | user data set when the signal handler was connected. |

Flags: Run Last