{% extends "base.html" %}

{% block title %}{{ namespace.name }}.{{ class.name }}.{{ method.name }}{% endblock %}

{% block meta_other %}
  <meta priority="og:title" content="{{ namespace.name }}.{{ class.name }}.{{ method.name }}"/>
  <meta priority="og:description" content="Reference for {{ namespace.name }}.{{ class.name }}.{{ method.name }}"/>
  <meta name="twitter:title" content="{{ namespace.name }}.{{ class.name }}.{{ method.name }}"/>
  <meta name="twitter:description" content="Reference for {{ namespace.name }}.{{ class.name }}.{{ method.name }}"/>
{% endblock %}

{% block sidebar %}
<div class="section">
  <h5>Type</h5>
  <div class="links">
    <a href="{{ class.link_prefix }}.{{ class.name }}.html">{{ class.name }}</a>
  </div>
</div>
<div class="section">
  <h5>Methods</h5>
  <div class="links">
  {% for m in class.methods %}
    <a class="method{% if method.name == m.name %} current{% endif %}" href="method.{{ class.name }}.{{ m.name }}.html">{{ m.name }}</a>
  {% endfor %}
  </div>
</div>
{% endblock %}

{% block content %}
<section id="main" class="content">
  <header>
    <h3>Method</h3>
    <h1><a href="index.html">{{ namespace.name }}</a><span class="sep"></span><a href="{{ class.link_prefix }}.{{ class.name }}.html">{{ class.name }}</a><span class="sep"></span>{{ method.name }}</h1>
  </header>

  <section>
    <div class="docblock">
      <p>
      {%- if CONFIG.is_unstable(method.available_since) -%}
      <span class="emblem available-next" title="This method will be available in the next stable release">unstable</span>&nbsp;
      {%- endif %}
      {%- if method.deprecated_since -%}
      <span class="emblem deprecated">deprecated: {{ method.deprecated_since.version }}</span>&nbsp;
      {%- endif -%}
      {%- if method.available_since -%}
      <span class="emblem available">since: {{ method.available_since }}</span>
      {%- endif -%}
      </p>
    </div>

    <div class="declaration toggle-wrapper">
      <h4 style="display:flex;" id="declaration">
        Declaration
        <a class="anchor" href="#declaration"></a>
        {% if CONFIG.source_location_url and method.source_location %}
        <a class="srclink" title="go to source location" href="{{ CONFIG.source_link(method.source_location) }}">[src]</a>
        {% endif %}
      </h4>

      <div class="docblock c-decl">
        <pre><code>{{ method.c_decl|safe }}</code></pre>
      </div>
    </div>

    <div class="description toggle-wrapper">
      <h4 style="display:flex;" id="description">
        Description
        <a class="anchor" href="#description"></a>
        {% if CONFIG.source_location_url and method.docs_location %}
        <a class="srclink" title="go to source location" href="{{ CONFIG.source_link(method.docs_location) }}">[src]</a>
        {% endif %}
      </h4>

      <div class="docblock">
        {{ method.description|safe }}
      </div>

      <div class="docblock">
        {% if method.stability -%}
        <p>Stability: {{ method.stability }}</p>
        {%- endif %}
        {% if method.available_since -%}
        <p>Available since: {{ method.available_since }}</p>
        {%- endif %}
        {% if method.deprecated_since -%}
        <div class="admonition deprecation">
          <p class="admonition-title">Deprecated since: {{ method.deprecated_since.version }}</p>
          {%- if method.deprecated_since.message -%}
          {{ method.deprecated_since.message }}
          {%- else -%}
          <p>Do not use in newly written code.</p>
          {%- endif -%}
        </div>
        {%- endif %}
        {% if method.finish_func -%}
        <p>This method completes asynchronously. Use <a href="method.{{class.name}}.{{method.finish_func}}.html"><code>{{method.finish_func_symbol}}()</code></a> inside the <code>GAsyncReadyCallback</code> to obtain the result of the operation.</p>
        {%- endif %}
        {% if not method.introspectable -%}
        <p>This method is not directly available to language bindings.</p>
        {%- endif %}
        {% if method.shadows -%}
        <p>This method is renamed to <a href="method.{{class.name}}.{{method.shadows}}.html"><code>{{method.shadows_symbol}}()</code></a> in language bindings.</p>
        {%- endif %}
        {% if method.shadowed_by -%}
        <p>The implementation of this method is provided by <a href="method.{{class.name}}.{{method.shadowed_by}}.html"><code>{{method.shadowed_by_symbol}}()</code></a> in language bindings.</p>
        {%- endif %}
      </div>

      {% if method.attributes %}
      <div class="docblock">
        <table>
        {% for (key, value) in method.attributes.items()|sort %}
          <tr><td>{{ key|escape }}</td><td>{{ value|escape }}</td></tr>
        {% endfor %}
        </table>
      </div>
      {% endif %}
    </div>

    {% if method.arguments|length != 0 %}
    <div class="parameters toggle-wrapper">
      <h4 id="parameters">
        Parameters
        <a href="#parameters" class="anchor"></a>
      </h4>

      <div class="docblock">
        <dl class="arguments">
          {% for arg in method.arguments %}
          <dt class="arg-name"><code>{{ arg.name }}</code></dt>
          <dd class="arg-description">
            <p><em>Type:</em>&nbsp;
            {%- if arg.is_array -%}An array of&nbsp;{%- endif -%}
            {%- if arg.is_list -%}A list of&nbsp;{%- endif -%}
            {%- if arg.link -%}
            {{ arg.link|safe }}
            {%- else -%}
            <code>{{ arg.type_cname }}</code>
            {%- endif -%}
            </p>
            {{ arg.description|safe }}
            <table>
            {% if arg.direction != "in" %}<tr><td title="direction: {{ arg.direction}}">{{ arg.direction_note }}</td></tr>{% endif %}
            {% if arg.direction == "in" and arg.nullable %}<tr><td>The argument can be <code>NULL</code>.</td></tr>{% endif %}
            {% if arg.direction in ["inout", "out"] and arg.nullable %}<tr><td>The argument can be set to <code>NULL</code> by the method.</td></tr>{% endif %}
            {% if arg.optional %}<tr><td>The argument can be <code>NULL</code>.</td></tr>{% endif %}
            {% if arg.is_array and arg.zero_terminated %}<tr><td>The array must be <code>NULL</code>-terminated.</td></tr>{% endif %}
            {% if arg.is_array and arg.fixed_size > 0 %}<tr><td>The array must have {{ arg.fixed_size }} elements.</td></tr>{% endif %}
            {% if arg.is_array and arg.len_arg %}<tr><td>The length of the array is specified in the <code>{{ arg.len_arg }}</code> argument.</td></tr>{% endif %}
            {% if arg.is_pointer %}<tr><td title="transfer: {{ arg.transfer }}">{{ arg.transfer_note }}</td></tr>{% endif %}
            {% if arg.string_note %}<tr><td>{{ arg.string_note }}</td></tr>{% endif %}
            </table>
          </dd>
          {% endfor %}

          {% if method.throws %}
          <dt class="arg-name"><code>error</code></dt>
          <dd class="arg-description">
            <p><em>Type:</em>&nbsp;<a href="javascript:void(0)" data-namespace="GLib" data-link="struct.Error.html" class="external"><code>GError **</code></a></p>
            <p>The return location for <a href="https://docs.gtk.org/glib/error-reporting.html#rules-for-use-of-gerror">a recoverable error</a>.</p>
            <table>
              <tr><td>The argument can be <code>NULL</code>.</td></tr>
              <tr><td>If the return location is not <code>NULL</code>, then you must initialize it to a <code>NULL</code> <code>GError*</code>.</td></tr>
              <tr><td>The argument will be left initialized to <code>NULL</code> by the method if there are no errors.</td></tr>
              <tr><td>In case of error, the argument will be set to a newly allocated <code>GError</code>; the caller will take ownership of the data, and be responsible for freeing it.</td></tr>
            </table>
          </dd>
          {% endif %}
        </dl>
      </div>
    </div>
    {% endif %}

    {% if method.return_value %}
    <div class="return-value toggle-wrapper">
      <h4 id="return-value">
        Return value
        <a href="#return-value" class="anchor"></a>
      </h4>

      <div class="docblock">
        <div class="returns">
          <div class="arg-description">
            <p><em>Type:</em>&nbsp;
            {%- if method.return_value.is_array -%}An array of&nbsp;{%- endif -%}
            {%- if method.return_value.is_list -%}A list of&nbsp;{%- endif -%}
            {%- if method.return_value.is_list_model -%}A list model of&nbsp;{%- endif -%}
            {%- if method.return_value.link -%}
            {{ method.return_value.link|safe }}
            {%- else -%}
            <code>{{ method.return_value.type_cname }}</code>
            {%- endif -%}
            </p>
            {{ method.return_value.description|safe }}
          </div>
          <div>
            <table>
            {% if method.return_value.is_array and method.return_value.zero_terminated %}<tr><td>The array is <code>NULL</code>-terminated.</td></tr>{% endif %}
            {% if method.return_value.is_array and method.return_value.fixed_size > 0 %}<tr><td>The array has {{ method.return_value.fixed_size }} elements.</td></tr>{% endif %}
            {% if method.return_value.is_array and method.return_value.len_arg %}<tr><td>The length of the array is in the <code>{{ method.return_value.len_arg }}</code> argument.</td></tr>{% endif %}
            {% if method.return_value.is_pointer %}<tr><td title="transfer: {{ method.return_value.transfer }}">{{ method.return_value.transfer_note }}</td></tr>{% endif %}
            {% if method.return_value.is_pointer and method.return_value.nullable %}<tr><td>The return value can be <code>NULL</code>.</td></tr>{% endif %}
            {% if method.return_value.string_note %}<tr><td>{{ method.return_value.string_note }}</td></tr>{% endif %}
            </table>
          </div>
        </div>
      </div>
    </div>
    {% endif %}

  </section>
</section>
{% endblock %}