## PolKitGnomeToggleAction

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

## Synopsis

                        PolKitGnomeToggleActionPrivate;
                        PolKitGnomeToggleAction;
    PolKitGnomeToggleAction* polkit_gnome_toggle_action_new (const gchar *name);
    PolKitGnomeToggleAction* polkit_gnome_toggle_action_new_default
                                                            (const gchar *name,
                                                             PolKitAction *polkit_action,
                                                             const gchar *locked_label,
                                                             const gchar *unlocked_label);
    GtkWidget*          polkit_gnome_toggle_action_create_toggle_button
                                                            (PolKitGnomeToggleAction *action);

## Object Hierarchy

      GObject
       +----GtkAction
             +----PolKitGnomeAction
                   +----PolKitGnomeToggleAction

## Implemented Interfaces

PolKitGnomeToggleAction implements GtkBuildable.

## Properties

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

## Signals

      "toggled"                                        : Run Last

## Description

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

## Details

### PolKitGnomeToggleActionPrivate

    typedef struct _PolKitGnomeToggleActionPrivate PolKitGnomeToggleActionPrivate;

### PolKitGnomeToggleAction

    typedef struct _PolKitGnomeToggleAction PolKitGnomeToggleAction;

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

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

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

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

`action` : | The PolKitGnomeToggleAction object
Returns : | A GtkToggleButton instance connected to the action

## Property Details

### The `"auth-underway-icon-name"` property

      "auth-underway-icon-name"  gchar*                : Read / Write

When authentication is underway, use this icon-name.

Default value: NULL

### The `"auth-underway-label"` property

      "auth-underway-label"      gchar*                : Read / Write

When authentication is underway, use this label.

Default value: NULL

### The `"auth-underway-sensitive"` property

      "auth-underway-sensitive"  gboolean              : Read / Write

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

Default value: TRUE

### The `"auth-underway-short-label"` property

      "auth-underway-short-label" gchar*                : Read / Write

When authentication is underway, use this short-label.

Default value: NULL

### The `"auth-underway-tooltip"` property

      "auth-underway-tooltip"    gchar*                : Read / Write

When authentication is underway, use this tooltip.

Default value: NULL

### The `"auth-underway-visible"` property

      "auth-underway-visible"    gboolean              : Read / Write

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

Default value: TRUE

## Signal Details

### The `"toggled"` signal

    void                user_function                      (PolKitGnomeToggleAction *toggle_action,
                                                            gpointer                 user_data)          : Run Last

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

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