![]() |
![]() |
![]() |
polkit-gtk-1 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
PolkitLockButtonPrivate; PolkitLockButton; 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_unlock_tooltip (PolkitLockButton *button, const gchar *tooltip); void polkit_lock_button_set_lock_text (PolkitLockButton *button, const gchar *text); void polkit_lock_button_set_lock_tooltip (PolkitLockButton *button, const gchar *tooltip); void polkit_lock_button_set_lock_down_text (PolkitLockButton *button, const gchar *text); void polkit_lock_button_set_lock_down_tooltip (PolkitLockButton *button, const gchar *tooltip); void polkit_lock_button_set_not_authorized_text (PolkitLockButton *button, const gchar *text); void polkit_lock_button_set_not_authorized_tooltip (PolkitLockButton *button, const gchar *tooltip);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBox +----GtkHBox +----PolkitLockButton
PolkitLockButton implements GtkBuildable, AtkImplementorIface and GtkOrientable.
"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-lock-down" gchar* : Read / Write / Construct "text-not-authorized" gchar* : Read / Write / Construct "text-unlock" gchar* : Read / Write / Construct "tooltip-lock" gchar* : Read / Write / Construct "tooltip-lock-down" gchar* : Read / Write / Construct "tooltip-not-authorized" gchar* : Read / Write / Construct "tooltip-unlock" gchar* : Read / Write / Construct
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 */ }
typedef struct _PolkitLockButton PolkitLockButton;
The PolkitLockButton structure contains only private data and should be accessed using the provided API.
GtkWidget * polkit_lock_button_new (const gchar *action_id);
Constructs a PolkitLockButton for action_id
.
|
An action identifer. |
Returns : |
A PolkitLockButton. |
gboolean polkit_lock_button_get_is_authorized (PolkitLockButton *button);
Gets whether the process is authorized.
|
A PolkitLockButton. |
Returns : |
TRUE if authorized.
|
gboolean polkit_lock_button_get_is_visible (PolkitLockButton *button);
Gets whether button
is currently being shown.
|
A PolkitLockButton. |
Returns : |
TRUE if button has any visible UI elements.
|
gboolean polkit_lock_button_get_can_obtain (PolkitLockButton *button);
Gets whether the user can obtain an authorization through authentication.
|
A PolkitLockButton. |
Returns : |
Whether the authorization is obtainable. |
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.
|
A PolkitLockButton. |
|
The text to set. |
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.
|
A PolkitLockButton. |
|
The text of the tooltip. |
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.
|
A PolkitLockButton. |
|
The text to set. |
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.
|
A PolkitLockButton. |
|
The text of the tooltip. |
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.
|
A PolkitLockButton. |
|
The text to set. |
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.
|
A PolkitLockButton. |
|
The text of the tooltip. |
void polkit_lock_button_set_not_authorized_text (PolkitLockButton *button, const gchar *text);
Makes button
display text
when an authorization cannot be obtained.
|
A PolkitLockButton. |
|
The text to set. |
void polkit_lock_button_set_not_authorized_tooltip (PolkitLockButton *button, const gchar *tooltip);
Makes button
display tooltip
when an authorization cannot be obtained.
|
A PolkitLockButton. |
|
The text of the tooltip. |
"action-id"
property"action-id" gchar* : Read / Write / Construct Only
The action identifier to use for the button.
Default value: NULL
"can-obtain"
property"can-obtain" gboolean : Read
Whether authorization can be obtained.
Default value: FALSE
"is-authorized"
property"is-authorized" gboolean : Read
Whether the process is authorized.
Default value: FALSE
"is-visible"
property"is-visible" gboolean : Read
Whether the widget is visible.
Default value: TRUE
"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"
"text-lock-down"
property"text-lock-down" gchar* : Read / Write / Construct
The text to display when prompting the user to lock down the action for all users.
Default value: "Click to lock down"
"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"
"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"
"tooltip-lock"
property"tooltip-lock" gchar* : Read / Write / Construct
The tooltip to display when prompting the user to lock.
Default value: "To prevent further changes, click the lock."
"tooltip-lock-down"
property"tooltip-lock-down" gchar* : Read / Write / Construct
The tooltip to display when prompting the user to lock down the action for all users.
Default value: "To prevent users without administrative privileges from making changes, click the lock."
"tooltip-not-authorized"
property"tooltip-not-authorized" gchar* : Read / Write / Construct
The tooltip to display when the user cannot obtain authorization through authentication.
Default value: "System policy prevents changes. Contact your system administator."
"tooltip-unlock"
property"tooltip-unlock" gchar* : Read / Write / Construct
The tooltip to display when prompting the user to unlock.
Default value: "Authentication is needed to make changes."
"changed"
signalvoid user_function (PolkitLockButton *button, gpointer user_data) : Run Last
Emitted when something on button
changes.
|
A PolkitLockButton. |
|
user data set when the signal handler was connected. |