PolkitLockButton

PolkitLockButton — Widget for obtaining/revoking authorizations

Stability Level

Stable, unless otherwise indicated

Functions

GtkWidget * polkit_lock_button_new ()
gboolean polkit_lock_button_get_is_authorized ()
gboolean polkit_lock_button_get_is_visible ()
gboolean polkit_lock_button_get_can_obtain ()
void polkit_lock_button_set_unlock_text ()
void polkit_lock_button_set_unlock_tooltip ()
void polkit_lock_button_set_lock_text ()
void polkit_lock_button_set_lock_tooltip ()
void polkit_lock_button_set_lock_down_text ()
void polkit_lock_button_set_lock_down_tooltip ()
void polkit_lock_button_set_not_authorized_text ()
void polkit_lock_button_set_not_authorized_tooltip ()

Properties

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

Signals

void changed Run Last

Types and Values

  PolkitLockButton
struct PolkitLockButtonClass

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkBox
                    ╰── PolkitLockButton

Implemented Interfaces

PolkitLockButton implements AtkImplementorIface, GtkBuildable and GtkOrientable.

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 and the Authority Implementation supports lock-down, the widget looks like this

allowing the user to lock down the action. The lockdown can be removed by right clicking the button - the user can discover this through the tooltip. If the Authority implementation does not support lockdown, 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. 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 obtained through authentication (and retained) or where users are implictly authorized (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 */
}

Functions

polkit_lock_button_new ()

GtkWidget *
polkit_lock_button_new (const gchar *action_id);

Constructs a PolkitLockButton for action_id .

Parameters

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.

Parameters

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.

Parameters

button

A PolkitLockButton.

  

Returns

TRUE if button has any 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.

Parameters

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 not authorized and clicking the button will obtain the authorization.

Parameters

button

A PolkitLockButton.

  

text

The text to set.

  

polkit_lock_button_set_unlock_tooltip ()

void
polkit_lock_button_set_unlock_tooltip (PolkitLockButton *button,
                                       const gchar *tooltip);

Makes button display tooltip when not authorized and clicking the button will obtain the authorization.

Parameters

button

A PolkitLockButton.

  

tooltip

The text of the tooltip.

  

polkit_lock_button_set_lock_text ()

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

Makes button display text when authorized and clicking the button will revoke the authorization.

Parameters

button

A PolkitLockButton.

  

text

The text to set.

  

polkit_lock_button_set_lock_tooltip ()

void
polkit_lock_button_set_lock_tooltip (PolkitLockButton *button,
                                     const gchar *tooltip);

Makes button display tooltip when authorized and clicking the button will revoke the authorization.

Parameters

button

A PolkitLockButton.

  

tooltip

The text of the tooltip.

  

polkit_lock_button_set_lock_down_text ()

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

Makes button display text when authorized and it is possible to lock down the action.

Parameters

button

A PolkitLockButton.

  

text

The text to set.

  

polkit_lock_button_set_lock_down_tooltip ()

void
polkit_lock_button_set_lock_down_tooltip
                               (PolkitLockButton *button,
                                const gchar *tooltip);

Makes button display tooltip when authorized and it is possible to lock down the action.

Parameters

button

A PolkitLockButton.

  

tooltip

The text of the tooltip.

  

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 an authorization cannot be obtained.

Parameters

button

A PolkitLockButton.

  

text

The text to set.

  

polkit_lock_button_set_not_authorized_tooltip ()

void
polkit_lock_button_set_not_authorized_tooltip
                               (PolkitLockButton *button,
                                const gchar *tooltip);

Makes button display tooltip when an authorization cannot be obtained.

Parameters

button

A PolkitLockButton.

  

tooltip

The text of the tooltip.

  

Types and Values

PolkitLockButton

typedef struct _PolkitLockButton PolkitLockButton;

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

Members

struct PolkitLockButtonClass

struct PolkitLockButtonClass {
	GtkBoxClass parent_class;

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

Class structure for PolkitLockButton.

Members

changed ()

Signal class handler for the “changed” signal.

  

Property Details

The “action-id” property

  “action-id”                gchar *

The action identifier to use for the button.

Flags: Read / Write / Construct Only

Default value: NULL

The “can-obtain” property

  “can-obtain”               gboolean

Whether authorization can be obtained.

Flags: Read

Default value: FALSE

The “is-authorized” property

  “is-authorized”            gboolean

Whether the process is authorized.

Flags: Read

Default value: FALSE

The “is-visible” property

  “is-visible”               gboolean

Whether the widget is visible.

Flags: Read

Default value: TRUE

The “text-lock” property

  “text-lock”                gchar *

The text to display when prompting the user to lock.

Flags: Read / Write / Construct

Default value: "Click to prevent changes"

The “text-lock-down” property

  “text-lock-down”           gchar *

The text to display when prompting the user to lock down the action for all users.

Flags: Read / Write / Construct

Default value: "Click to lock down"

The “text-not-authorized” property

  “text-not-authorized”      gchar *

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

Flags: Read / Write / Construct

Default value: "Not authorized to make changes"

The “text-unlock” property

  “text-unlock”              gchar *

The text to display when prompting the user to unlock.

Flags: Read / Write / Construct

Default value: "Click to make changes"

The “tooltip-lock” property

  “tooltip-lock”             gchar *

The tooltip to display when prompting the user to lock.

Flags: Read / Write / Construct

Default value: "To prevent further changes, click the lock."

The “tooltip-lock-down” property

  “tooltip-lock-down”        gchar *

The tooltip to display when prompting the user to lock down the action for all users.

Flags: Read / Write / Construct

Default value: "To prevent users without administrative privileges from making changes, click the lock."

The “tooltip-not-authorized” property

  “tooltip-not-authorized”   gchar *

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

Flags: Read / Write / Construct

Default value: "System policy prevents changes. Contact your system administator."

The “tooltip-unlock” property

  “tooltip-unlock”           gchar *

The tooltip to display when prompting the user to unlock.

Flags: Read / Write / Construct

Default value: "Authentication is needed to make changes."

Signal Details

The “changed” signal

void
user_function (PolkitLockButton *button,
               gpointer          user_data)

Emitted when something on button changes.

Parameters

button

A PolkitLockButton.

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Generated by GTK-Doc V1.26