PolkitLockButton

PolkitLockButton — Toggle button for obtaining/revoking authorizations

Stability Level

Stable, unless otherwise indicated

Synopsis

                    PolkitLockButton;
                    PolkitLockButtonClass;
GtkWidget *         polkit_lock_button_new              (const gchar *action_id);
gboolean            polkit_lock_button_get_is_authorized
                                                        (PolkitLockButton *button);
gboolean            polkit_lock_button_get_is_visible   (PolkitLockButton *button);
gboolean            polkit_lock_button_get_can_obtain   (PolkitLockButton *button);
void                polkit_lock_button_set_unlock_text  (PolkitLockButton *button,
                                                         const gchar *text);
void                polkit_lock_button_set_lock_text    (PolkitLockButton *button,
                                                         const gchar *text);
void                polkit_lock_button_set_not_authorized_text
                                                        (PolkitLockButton *button,
                                                         const gchar *text);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBox
                                 +----GtkHBox
                                       +----PolkitLockButton

Implemented Interfaces

PolkitLockButton implements GtkBuildable, AtkImplementorIface and GtkOrientable.

Properties

  "action-id"                gchar*                : Read / Write / Construct Only
  "can-obtain"               gboolean              : Read
  "is-authorized"            gboolean              : Read
  "is-visible"               gboolean              : Read
  "text-lock"                gchar*                : Read / Write / Construct
  "text-not-authorized"      gchar*                : Read / Write / Construct
  "text-unlock"              gchar*                : Read / Write / Construct

Signals

  "changed"                                        : Run Last

Description

PolkitLockButton is a widget that can be used in control panels to allow users to obtain and revoke authorizations needed for the control panel UI to function.

If the user lacks the authorization but authorization can be obtained through authentication, the widget looks like this

and the user can click the button to obtain the authorization. This will pop up an authentication dialog. Once authorization is obtained, the widget changes to this

and the authorization can be dropped by clicking the button. If the user is not able to obtain authorization at all, the widget looks like this

If the user is authorized (either implicitly via the .policy file defaults or through e.g. Local Authority configuration) and no authentication is necessary, the widget will be hidden.

Finally, if the user is not authorized but authorization can be obtained and the obtained authorization will be a one-shot authorization, the widget will be hidden as well. This means that any attempt to use the Mechanism that requires authorization for the specified action will always prompt for authentication. This condition happens exactly when (!polkit_lock_button_get_is_authorized() && polkit_lock_button_get_can_obtain() && !polkit_lock_button_get_is_visible()) is TRUE.

Typically PolkitLockButton is only useful for actions where authorization is retained (cf. the defaults specified in the .policy file for the action) but note that this behavior can be overridden by the Authority implementation.

The typical usage of this widget is like this:

static void
update_sensitivity_according_to_lock_button (FooBar *bar)
{
  gboolean make_sensitive;

  make_sensitive = FALSE;
  if (polkit_lock_button_get_is_authorized (POLKIT_LOCK_BUTTON (bar->priv->lock_button)))
    {
      make_sensitive = TRUE;
    }
  else
    {
      /* Catch the case where authorization is one-shot - this means
       * an authentication dialog will be shown every time a widget the user
       * manipulates calls into the Mechanism.
       */
      if (polkit_lock_button_get_can_obtain (POLKIT_LOCK_BUTTON (bar->priv->lock_button)) &&
          !polkit_lock_button_get_is_visible (POLKIT_LOCK_BUTTON (bar->priv->lock_button)))
        make_sensitive = TRUE;
    }


  /* Make all widgets relying on authorization sensitive according to
   * the value of make_sensitive.
   */
}

static void
on_lock_button_changed (PolkitLockButton *button,
                        gpointer          user_data)
{
  FooBar *bar = FOO_BAR (user_data);

  update_sensitivity_according_to_lock_button (bar);
}

static void
foo_bar_init (FooBar *bar)
{
  /* Construct other widgets */

  bar->priv->lock_button = polkit_lock_button_new ("org.project.mechanism.action-name");
  g_signal_connect (bar->priv->lock_button,
                    "changed",
                    G_CALLBACK (on_lock_button_changed),
                    bar);
  update_sensitity_according_to_lock_button (bar);

  /* Pack bar->priv->lock_button into widget hierarchy */
}

Details

PolkitLockButton

typedef struct _PolkitLockButton PolkitLockButton;

The PolkitLockButton structure contains only private data and should be accessed using the provided API.


PolkitLockButtonClass

typedef struct {
  GtkHBoxClass parent_class;

  /* Signals */
  void (*changed) (PolkitLockButton *button);
} PolkitLockButtonClass;

Class structure for PolkitLockButton.

GtkHBoxClass parent_class;

The parent class structure.

changed ()

Signal class handler for the "changed" signal.

polkit_lock_button_new ()

GtkWidget *         polkit_lock_button_new              (const gchar *action_id);

Constructs a PolkitLockButton for action_id.

action_id :

An action identifer.

Returns :

A PolkitLockButton.

polkit_lock_button_get_is_authorized ()

gboolean            polkit_lock_button_get_is_authorized
                                                        (PolkitLockButton *button);

Gets whether the process is authorized.

button :

A PolkitLockButton.

Returns :

TRUE if authorized.

polkit_lock_button_get_is_visible ()

gboolean            polkit_lock_button_get_is_visible   (PolkitLockButton *button);

Gets whether button is currently being shown.

button :

A PolkitLockButton.

Returns :

TRUE if button has visible UI elements.

polkit_lock_button_get_can_obtain ()

gboolean            polkit_lock_button_get_can_obtain   (PolkitLockButton *button);

Gets whether the user can obtain an authorization through authentication.

button :

A PolkitLockButton.

Returns :

Whether the authorization is obtainable.

polkit_lock_button_set_unlock_text ()

void                polkit_lock_button_set_unlock_text  (PolkitLockButton *button,
                                                         const gchar *text);

Makes button display text when the prompting the user to unlock.

button :

A PolkitLockButton.

text :

The text to set.

polkit_lock_button_set_lock_text ()

void                polkit_lock_button_set_lock_text    (PolkitLockButton *button,
                                                         const gchar *text);

Makes button display text when the prompting the user to unlock.

button :

A PolkitLockButton.

text :

The text to set.

polkit_lock_button_set_not_authorized_text ()

void                polkit_lock_button_set_not_authorized_text
                                                        (PolkitLockButton *button,
                                                         const gchar *text);

Makes button display text when the prompting the user to unlock.

button :

A PolkitLockButton.

text :

The text to set.

Property Details

The "action-id" property

  "action-id"                gchar*                : Read / Write / Construct Only

The action identifier to use for the button.

Default value: NULL


The "can-obtain" property

  "can-obtain"               gboolean              : Read

Whether authorization can be obtained.

Default value: FALSE


The "is-authorized" property

  "is-authorized"            gboolean              : Read

Whether the process is authorized.

Default value: FALSE


The "is-visible" property

  "is-visible"               gboolean              : Read

Whether the widget is visible.

Default value: TRUE


The "text-lock" property

  "text-lock"                gchar*                : Read / Write / Construct

The text to display when prompting the user to lock.

Default value: "Click to prevent changes"


The "text-not-authorized" property

  "text-not-authorized"      gchar*                : Read / Write / Construct

The text to display when the user cannot obtain authorization through authentication.

Default value: "Not authorized to make changes"


The "text-unlock" property

  "text-unlock"              gchar*                : Read / Write / Construct

The text to display when prompting the user to unlock.

Default value: "Click to make changes"

Signal Details

The "changed" signal

void                user_function                      (PolkitLockButton *button,
                                                        gpointer          user_data)      : Run Last

Emitted when something on button changes.

button :

A PolkitLockButton.

user_data :

user data set when the signal handler was connected.