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 'stock_lock' by default except for the YES PolicyKit answer where it's set to 'stock_lock-open'. 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.