<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="GtkLockButton">
<refmeta>
<refentrytitle role="top_of_page" id="GtkLockButton.top_of_page">GtkLockButton</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkLockButton</refname>
<refpurpose>A widget to unlock or lock privileged operations</refpurpose>
</refnamediv>

<refsect1 id="GtkLockButton.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-lock-button-new">gtk_lock_button_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GPermission"><returnvalue>GPermission</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-lock-button-get-permission">gtk_lock_button_get_permission</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-lock-button-set-permission">gtk_lock_button_set_permission</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkLockButton.properties" role="properties">
<title role="properties.title">Properties</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="properties_type" colwidth="150px"/>
<colspec colname="properties_name" colwidth="300px"/>
<colspec colname="properties_flags" colwidth="200px"/>
<tbody>
<row><entry role="property_type"><link linkend="GPermission"><type>GPermission</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkLockButton--permission">permission</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="gchar"><type>gchar</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkLockButton--text-lock">text-lock</link></entry><entry role="property_flags">Read / Write / Construct</entry></row>
<row><entry role="property_type"><link linkend="gchar"><type>gchar</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkLockButton--text-unlock">text-unlock</link></entry><entry role="property_flags">Read / Write / Construct</entry></row>
<row><entry role="property_type"><link linkend="gchar"><type>gchar</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkLockButton--tooltip-lock">tooltip-lock</link></entry><entry role="property_flags">Read / Write / Construct</entry></row>
<row><entry role="property_type"><link linkend="gchar"><type>gchar</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkLockButton--tooltip-not-authorized">tooltip-not-authorized</link></entry><entry role="property_flags">Read / Write / Construct</entry></row>
<row><entry role="property_type"><link linkend="gchar"><type>gchar</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkLockButton--tooltip-unlock">tooltip-unlock</link></entry><entry role="property_flags">Read / Write / Construct</entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkLockButton.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GtkLockButton-struct">GtkLockButton</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkLockButton.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
        <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GtkWidget">GtkWidget</link>
            <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GtkButton">GtkButton</link>
                <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkLockButton
</screen>
</refsect1>
<refsect1 id="GtkLockButton.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkLockButton implements
 <link linkend="AtkImplementorIface">AtkImplementorIface</link>,  <link linkend="GtkBuildable">GtkBuildable</link>,  <link linkend="GtkConstraintTarget">GtkConstraintTarget</link> and  <link linkend="GtkActionable">GtkActionable</link>.</para>

</refsect1>

<refsect1 id="GtkLockButton.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="GtkLockButton.description" role="desc">
<title role="desc.title">Description</title>
<para>GtkLockButton is a widget that can be used in control panels or
preference dialogs to allow users to obtain and revoke authorizations
needed to operate the controls. The required authorization is represented
by a <link linkend="GPermission"><type>GPermission</type></link> object. Concrete implementations of <link linkend="GPermission"><type>GPermission</type></link> may use
PolicyKit or some other authorization framework. To obtain a PolicyKit-based
<link linkend="GPermission"><type>GPermission</type></link>, use <link linkend="polkit-permission-new"><function>polkit_permission_new()</function></link>.</para>
<para>If the user is not currently allowed to perform the action, but can obtain
the permission, the widget looks like this:</para>
<para><inlinemediaobject><imageobject><imagedata fileref="lockbutton-locked.png"></imagedata></imageobject><textobject><phrase></phrase></textobject></inlinemediaobject></para>
<para>and the user can click the button to request the permission. Depending
on the platform, this may pop up an authentication dialog or ask the user
to authenticate in some other way. Once the user has obtained the permission,
the widget changes to this:</para>
<para><inlinemediaobject><imageobject><imagedata fileref="lockbutton-unlocked.png"></imagedata></imageobject><textobject><phrase></phrase></textobject></inlinemediaobject></para>
<para>and the permission can be dropped again by clicking the button. If the user
is not able to obtain the permission at all, the widget looks like this:</para>
<para><inlinemediaobject><imageobject><imagedata fileref="lockbutton-sorry.png"></imagedata></imageobject><textobject><phrase></phrase></textobject></inlinemediaobject></para>
<para>If the user has the permission and cannot drop it, the button is hidden.</para>
<para>The text (and tooltips) that are shown in the various cases can be adjusted
with the <link linkend="GtkLockButton--text-lock"><type>“text-lock”</type></link>, <link linkend="GtkLockButton--text-unlock"><type>“text-unlock”</type></link>,
<link linkend="GtkLockButton--tooltip-lock"><type>“tooltip-lock”</type></link>, <link linkend="GtkLockButton--tooltip-unlock"><type>“tooltip-unlock”</type></link> and
<link linkend="GtkLockButton--tooltip-not-authorized"><type>“tooltip-not-authorized”</type></link> properties.</para>

</refsect1>
<refsect1 id="GtkLockButton.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-lock-button-new" role="function">
<title>gtk_lock_button_new&#160;()</title>
<indexterm zone="gtk-lock-button-new"><primary>gtk_lock_button_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
gtk_lock_button_new (<parameter><link linkend="GPermission"><type>GPermission</type></link> *permission</parameter>);</programlisting>
<para>Creates a new lock button which reflects the <parameter>permission</parameter>
.</para>
<refsect3 id="gtk-lock-button-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>permission</para></entry>
<entry role="parameter_description"><para>a <link linkend="GPermission"><type>GPermission</type></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-lock-button-new.returns" role="returns">
<title>Returns</title>
<para> a new <link linkend="GtkLockButton"><type>GtkLockButton</type></link></para>
</refsect3></refsect2>
<refsect2 id="gtk-lock-button-get-permission" role="function">
<title>gtk_lock_button_get_permission&#160;()</title>
<indexterm zone="gtk-lock-button-get-permission"><primary>gtk_lock_button_get_permission</primary></indexterm>
<programlisting language="C"><link linkend="GPermission"><returnvalue>GPermission</returnvalue></link>&#160;*
gtk_lock_button_get_permission (<parameter><link linkend="GtkLockButton"><type>GtkLockButton</type></link> *button</parameter>);</programlisting>
<para>Obtains the <link linkend="GPermission"><type>GPermission</type></link> object that controls <parameter>button</parameter>
.</para>
<refsect3 id="gtk-lock-button-get-permission.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>button</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkLockButton"><type>GtkLockButton</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-lock-button-get-permission.returns" role="returns">
<title>Returns</title>
<para>the <link linkend="GPermission"><type>GPermission</type></link> of <parameter>button</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-lock-button-set-permission" role="function">
<title>gtk_lock_button_set_permission&#160;()</title>
<indexterm zone="gtk-lock-button-set-permission"><primary>gtk_lock_button_set_permission</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_lock_button_set_permission (<parameter><link linkend="GtkLockButton"><type>GtkLockButton</type></link> *button</parameter>,
                                <parameter><link linkend="GPermission"><type>GPermission</type></link> *permission</parameter>);</programlisting>
<para>Sets the <link linkend="GPermission"><type>GPermission</type></link> object that controls <parameter>button</parameter>
.</para>
<refsect3 id="gtk-lock-button-set-permission.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>button</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkLockButton"><type>GtkLockButton</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>permission</para></entry>
<entry role="parameter_description"><para>a <link linkend="GPermission"><type>GPermission</type></link> object, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkLockButton.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkLockButton-struct" role="struct">
<title>GtkLockButton</title>
<indexterm zone="GtkLockButton-struct"><primary>GtkLockButton</primary></indexterm>
<programlisting language="C">typedef struct _GtkLockButton GtkLockButton;</programlisting>
</refsect2>

</refsect1>
<refsect1 id="GtkLockButton.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkLockButton--permission" role="property"><title>The <literal>“permission”</literal> property</title>
<indexterm zone="GtkLockButton--permission"><primary>GtkLockButton:permission</primary></indexterm>
<programlisting>  “permission”               <link linkend="GPermission"><type>GPermission</type></link>&#160;*</programlisting>
<para>The GPermission object controlling this button.</para><para>Owner: GtkLockButton</para>
<para>Flags: Read / Write</para>
</refsect2>
<refsect2 id="GtkLockButton--text-lock" role="property"><title>The <literal>“text-lock”</literal> property</title>
<indexterm zone="GtkLockButton--text-lock"><primary>GtkLockButton:text-lock</primary></indexterm>
<programlisting>  “text-lock”                <link linkend="gchar"><type>gchar</type></link>&#160;*</programlisting>
<para>The text to display when prompting the user to lock.</para><para>Owner: GtkLockButton</para>
<para>Flags: Read / Write / Construct</para>
<para>Default value: "Lock"</para>
</refsect2>
<refsect2 id="GtkLockButton--text-unlock" role="property"><title>The <literal>“text-unlock”</literal> property</title>
<indexterm zone="GtkLockButton--text-unlock"><primary>GtkLockButton:text-unlock</primary></indexterm>
<programlisting>  “text-unlock”              <link linkend="gchar"><type>gchar</type></link>&#160;*</programlisting>
<para>The text to display when prompting the user to unlock.</para><para>Owner: GtkLockButton</para>
<para>Flags: Read / Write / Construct</para>
<para>Default value: "Unlock"</para>
</refsect2>
<refsect2 id="GtkLockButton--tooltip-lock" role="property"><title>The <literal>“tooltip-lock”</literal> property</title>
<indexterm zone="GtkLockButton--tooltip-lock"><primary>GtkLockButton:tooltip-lock</primary></indexterm>
<programlisting>  “tooltip-lock”             <link linkend="gchar"><type>gchar</type></link>&#160;*</programlisting>
<para>The tooltip to display when prompting the user to lock.</para><para>Owner: GtkLockButton</para>
<para>Flags: Read / Write / Construct</para>
<para>Default value: "Dialog is unlocked.\nClick to prevent further changes"</para>
</refsect2>
<refsect2 id="GtkLockButton--tooltip-not-authorized" role="property"><title>The <literal>“tooltip-not-authorized”</literal> property</title>
<indexterm zone="GtkLockButton--tooltip-not-authorized"><primary>GtkLockButton:tooltip-not-authorized</primary></indexterm>
<programlisting>  “tooltip-not-authorized”   <link linkend="gchar"><type>gchar</type></link>&#160;*</programlisting>
<para>The tooltip to display when prompting the user cannot obtain authorization.</para><para>Owner: GtkLockButton</para>
<para>Flags: Read / Write / Construct</para>
<para>Default value: "System policy prevents changes.\nContact your system administrator"</para>
</refsect2>
<refsect2 id="GtkLockButton--tooltip-unlock" role="property"><title>The <literal>“tooltip-unlock”</literal> property</title>
<indexterm zone="GtkLockButton--tooltip-unlock"><primary>GtkLockButton:tooltip-unlock</primary></indexterm>
<programlisting>  “tooltip-unlock”           <link linkend="gchar"><type>gchar</type></link>&#160;*</programlisting>
<para>The tooltip to display when prompting the user to unlock.</para><para>Owner: GtkLockButton</para>
<para>Flags: Read / Write / Construct</para>
<para>Default value: "Dialog is locked.\nClick to make changes"</para>
</refsect2>

</refsect1>

</refentry>
