~ubuntu-branches/ubuntu/vivid/glib2.0/vivid-proposed

Some of the GSettingsBackend functions accept or return a <a href="http://library.gnome.org/devel/glib/unstable/glib-Balanced-Binary-Trees.html#GTree">GTree</a>.

182

These trees always have strings as keys and <a href="http://library.gnome.org/devel/glib/unstable/glib-GVariant.html#GVariant">GVariant</a> as values.

183

<code class="function">g_settings_backend_create_tree()</code> is a convenience function to create

184

suitable trees.

185

The GSettingsBackend API is exported to allow third-party

210

<a name="g-settings-backend-changed"></a><h3>g_settings_backend_changed ()</h3>

211

<pre class="programlisting">void

212

g_settings_backend_changed (<code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend">GSettingsBackend</a> *backend</code>,

213

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *key</code>,

214

<code><a href="../glib/glib-Basic-Types.html#gpointer">gpointer</a> origin_tag</code>);</pre>

213

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *key</code>,

214

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer">gpointer</a> origin_tag</code>);</pre>

215

Signals that a single key has possibly changed. Backend

216

implementations should call this if a key has possibly changed its

217

value.

266

<a name="g-settings-backend-path-changed"></a><h3>g_settings_backend_path_changed ()</h3>

267

<pre class="programlisting">void

268

g_settings_backend_path_changed (<code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend">GSettingsBackend</a> *backend</code>,

269

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *path</code>,

270

<code><a href="../glib/glib-Basic-Types.html#gpointer">gpointer</a> origin_tag</code>);</pre>

269

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *path</code>,

270

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer">gpointer</a> origin_tag</code>);</pre>

271

Signals that all keys below a given path may have possibly changed.

272

Backend implementations should call this if an entire path of keys

273

have possibly changed their values.

322

<a name="g-settings-backend-keys-changed"></a><h3>g_settings_backend_keys_changed ()</h3>

323

<pre class="programlisting">void

324

g_settings_backend_keys_changed (<code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend">GSettingsBackend</a> *backend</code>,

325

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *path</code>,

326

<code><a href="../glib/glib-Basic-Types.html#gchar">gchar</a> const * const *items</code>,

327

<code><a href="../glib/glib-Basic-Types.html#gpointer">gpointer</a> origin_tag</code>);</pre>

325

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *path</code>,

326

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> const * const *items</code>,

327

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer">gpointer</a> origin_tag</code>);</pre>

328

Signals that a list of keys have possibly changed. Backend

329

implementations should call this if keys have possibly changed their

330

values.

369

</tr>

370

<tr>

371

<td class="parameter_name">items</td>

372

<td class="parameter_description"> the <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>-terminated list of changed keys. </td>

372

<td class="parameter_description"> the <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>-terminated list of changed keys. </td>

373

<td class="parameter_annotations">[<acronym title="Parameter points to an array of items.">array</acronym> zero-terminated=1]</td>

374

</tr>

375

<tr>

388

<pre class="programlisting">void

389

g_settings_backend_path_writable_changed

390

(<code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend">GSettingsBackend</a> *backend</code>,

391

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *path</code>);</pre>

391

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *path</code>);</pre>

392

Signals that the writability of all keys below a given path may have

393

changed.

394

Since GSettings performs no locking operations for itself, this call

422

<a name="g-settings-backend-writable-changed"></a><h3>g_settings_backend_writable_changed ()</h3>

423

<pre class="programlisting">void

424

g_settings_backend_writable_changed (<code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend">GSettingsBackend</a> *backend</code>,

425

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *key</code>);</pre>

425

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *key</code>);</pre>

426

Signals that the writability of a single key has possibly changed.

427

Since GSettings performs no locking operations for itself, this call

428

will always be made in response to external events.

455

<a name="g-settings-backend-changed-tree"></a><h3>g_settings_backend_changed_tree ()</h3>

456

<pre class="programlisting">void

457

g_settings_backend_changed_tree (<code><a class="link" href="GSettingsBackend.html" title="GSettingsBackend">GSettingsBackend</a> *backend</code>,

458

<code><a href="../glib/glib-Balanced-Binary-Trees.html#GTree">GTree</a> *tree</code>,

459

<code><a href="../glib/glib-Basic-Types.html#gpointer">gpointer</a> origin_tag</code>);</pre>

458

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Balanced-Binary-Trees.html#GTree">GTree</a> *tree</code>,

459

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer">gpointer</a> origin_tag</code>);</pre>

460

This call is a convenience wrapper. It gets the list of changes from

461

462

, computes the longest common prefix and calls

477

</tr>

478

<tr>

479

480

<td class="parameter_description">a <a href="../glib/glib-Balanced-Binary-Trees.html#GTree">GTree</a> containing the changes</td>

480

<td class="parameter_description">a <a href="http://library.gnome.org/devel/glib/unstable/glib-Balanced-Binary-Trees.html#GTree">GTree</a> containing the changes</td>

481

482

</tr>

483

<tr>

494

495

<a name="g-settings-backend-flatten-tree"></a><h3>g_settings_backend_flatten_tree ()</h3>

496

<pre class="programlisting">void

497

g_settings_backend_flatten_tree (<code><a href="../glib/glib-Balanced-Binary-Trees.html#GTree">GTree</a> *tree</code>,

498

<code><a href="../glib/glib-Basic-Types.html#gchar">gchar</a> **path</code>,

499

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> ***keys</code>,

500

<code><a href="../glib/glib-GVariant.html#GVariant">GVariant</a> ***values</code>);</pre>

497

g_settings_backend_flatten_tree (<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Balanced-Binary-Trees.html#GTree">GTree</a> *tree</code>,

498

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> **path</code>,

499

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> ***keys</code>,

500

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-GVariant.html#GVariant">GVariant</a> ***values</code>);</pre>

501

Calculate the longest common prefix of all keys in a tree and write

502

out an array of the key names relative to that prefix and,

503

optionally, the value to store at each of those keys.

505

, <code>keys</code>

506

and <code>values</code>

507

using

508

<a href="../glib/glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>. You should not attempt to free or unref the contents of

508

<a href="http://library.gnome.org/devel/glib/unstable/glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>. You should not attempt to free or unref the contents of

509

510

or <code>values</code>

511

.

520

<tbody>

521

<tr>

522

523

<td class="parameter_description">a <a href="../glib/glib-Balanced-Binary-Trees.html#GTree">GTree</a> containing the changes</td>

523

<td class="parameter_description">a <a href="http://library.gnome.org/devel/glib/unstable/glib-Balanced-Binary-Trees.html#GTree">GTree</a> containing the changes</td>

524

525

</tr>

526

<tr>

536

</tr>

537

<tr>

538

<td class="parameter_name">values</td>

539

<td class="parameter_description"> the location to save the values, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </td>

539

<td class="parameter_description"> the location to save the values, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </td>

540

<td class="parameter_annotations">[<acronym title="Parameter for returning results. Default is transfer full.">out</acronym>][<acronym title="NULL is ok, both for passing and for returning.">allow-none</acronym>][<acronym title="Free data container after the code is done.">transfer container</acronym>][<acronym title="Parameter points to an array of items.">array</acronym> zero-terminated=1]</td>

541

</tr>

542

</tbody>

548

549

<a name="g-keyfile-settings-backend-new"></a><h3>g_keyfile_settings_backend_new ()</h3>

550

<pre class="programlisting"><a class="link" href="GSettingsBackend.html" title="GSettingsBackend">GSettingsBackend</a> *

551

g_keyfile_settings_backend_new (<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *filename</code>,

552

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *root_path</code>,

553

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *root_group</code>);</pre>

551

g_keyfile_settings_backend_new (<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *filename</code>,

552

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *root_path</code>,

553

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *root_group</code>);</pre>

554

Creates a keyfile-backed <a class="link" href="GSettingsBackend.html" title="GSettingsBackend">GSettingsBackend</a>.

555

The filename of the keyfile to use is given by <code>filename</code>

556

.

560

not contain two consecutive slashes). <code>root_path</code>

561

may be "/".

562

If <code>root_group</code>

563

is non-<a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it specifies the name of the keyfile

563

is non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it specifies the name of the keyfile

564

group used for keys that are written directly below <code>root_path</code>

565

. For

566

example, if <code>root_path</code>

567

is "/apps/example/" and <code>root_group</code>

568

569

"toplevel", then settings the key "/apps/example/enabled" to a value

570

of <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> will cause the following to appear in the keyfile:

570

of <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> will cause the following to appear in the keyfile:

571

572

573

<tbody>

583

584

585

If <code>root_group</code>

586

is <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it is not permitted to store keys

586

is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> then it is not permitted to store keys

587

directly below the <code>root_path</code>

588

.

589

For keys not stored directly below <code>root_path</code>

607

608

609

The backend will refuse writes (and return writability as being

610

<a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>) for keys outside of <code>root_path</code>

610

<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>) for keys outside of <code>root_path</code>

611

and, in the event that

612

<code>root_group</code>

613

is <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, also for keys directly under <code>root_path</code>

613

is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, also for keys directly under <code>root_path</code>

614

615

Writes will also be refused if the backend detects that it has the

616

inability to rewrite the keyfile (ie: the containing directory is not

642

<td class="parameter_name">root_group</td>

643

<td class="parameter_description"> the group name corresponding to

644

645

, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </td>

645

, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </td>

646

<td class="parameter_annotations">[<acronym title="NULL is ok, both for passing and for returning.">allow-none</acronym>]</td>

647

</tr>

648

</tbody>

Older »