GNOME.org
 

[libhandy/wip/haecker-felix/flap-widget] Some docs

commit c1aa3bf332d2054bfd41dd86b4dcb7413cb7951e
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Tue Nov 24 15:54:06 2020 +0500

    Some docs

 src/hdy-flap.c | 164 +++++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 129 insertions(+), 35 deletions(-)
---
diff --git a/src/hdy-flap.c b/src/hdy-flap.c
index fc20848e..0b9fb4e3 100644
--- a/src/hdy-flap.c
+++ b/src/hdy-flap.c
@@ -25,25 +25,29 @@
 
 /**
  * HdyFlapFoldPolicy:
- * @HDY_FLAP_FOLD_POLICY_NEVER: No transition
- * @HDY_FLAP_FOLD_POLICY_ALWAYS: A cross-fade
- * @HDY_FLAP_FOLD_POLICY_AUTO: TBD
+ * @HDY_FLAP_FOLD_POLICY_NEVER: Disable folding
+ * @HDY_FLAP_FOLD_POLICY_ALWAYS: Keep the flap always folded
+ * @HDY_FLAP_FOLD_POLICY_AUTO: Fold and unfold the flap based on available space
  *
- * These enumeration values describe the possible transitions between children
- * in a #HdyFlap widget.
+ * These enumeration values describe the possible folding behavior in a #HdyFlap
+ * widget.
+ *
+ * Since: 1.1
  */
 
 /**
  * HdyFlapTransitionType:
- * @HDY_FLAP_TRANSITION_TYPE_OVER: No transition
- * @HDY_FLAP_TRANSITION_TYPE_UNDER: A cross-fade
+ * @HDY_FLAP_TRANSITION_TYPE_OVER: TBD
+ * @HDY_FLAP_TRANSITION_TYPE_UNDER: TBD
  * @HDY_FLAP_TRANSITION_TYPE_SLIDE: TBD
- * @HDY_FLAP_TRANSITION_TYPE_OVER_TRANSPARENT: a
+ * @HDY_FLAP_TRANSITION_TYPE_OVER_TRANSPARENT: TBD
  *
  * These enumeration values describe the possible transitions between children
  * in a #HdyFlap widget.
  *
  * New values may be added to this enum over time.
+ *
+ * Since: 1.1
  */
 
 #define HDY_SWIPE_BORDER 16
@@ -1432,12 +1436,14 @@ hdy_flap_class_init (HdyFlapClass *klass)
   /**
    * HdyFlap:reveal-duration:
    *
+   * The reveal transition animation duration, in milliseconds.
+   *
    * Since: 1.1
    */
   props[PROP_REVEAL_DURATION] =
     g_param_spec_uint ("reveal-duration",
                        _("Reveal Duration"),
-                       _("Reveal Duration"),
+                       _("The reveal transition animation duration, in milliseconds"),
                        0, G_MAXINT,
                        250,
                        G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
@@ -1470,12 +1476,14 @@ hdy_flap_class_init (HdyFlapClass *klass)
   /**
    * HdyFlap:fold-duration:
    *
+   * The fold transition animation duration, in milliseconds.
+   *
    * Since: 1.1
    */
   props[PROP_FOLD_DURATION] =
     g_param_spec_uint ("fold-duration",
                        _("Fold Duration"),
-                       _("Fold Duration"),
+                       _("The fold transition animation duration, in milliseconds"),
                        0, G_MAXINT,
                        250,
                        G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
@@ -1483,36 +1491,49 @@ hdy_flap_class_init (HdyFlapClass *klass)
   /**
    * HdyFlap:folded:
    *
+   * Whether the flap is currently folded.
+   *
+   * See #HdyFlap:fold-policy.
+   *
    * Since: 1.1
    */
   props[PROP_FOLDED] =
     g_param_spec_boolean ("folded",
                           _("Folded"),
-                          _("Folded"),
+                          _("Whether the flap is currently folded"),
                           FALSE,
                           G_PARAM_READABLE);
 
   /**
    * HdyFlap:locked:
    *
+   * Whether the flap is locked.
+   *
+   * If %FALSE, folding when the flap is revealed automatically closes it, and
+   * unfolding it when the flap is not revealed opens it. If %TRUE,
+   * #HdyFlap:reveal-flap value never changes on its own.
+   *
    * Since: 1.1
    */
   props[PROP_LOCKED] =
     g_param_spec_boolean ("locked",
                           _("Locked"),
-                          _("Locked"),
+                          _("Whether the flap is locked"),
                           FALSE,
                           G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
    * HdyFlap:transition-type:
    *
+   * The type of animation that will be used for reveal and fold transitions
+   * in @self.
+   *
    * Since: 1.1
    */
   props[PROP_TRANSITION_TYPE] =
     g_param_spec_enum ("transition-type",
                        _("Transition Type"),
-                       _("Transition Type"),
+                       _("The type of animation used for reveal and fold transitions"),
                        HDY_TYPE_FLAP_TRANSITION_TYPE,
                        HDY_FLAP_TRANSITION_TYPE_OVER,
                        G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
@@ -1520,36 +1541,50 @@ hdy_flap_class_init (HdyFlapClass *klass)
   /**
    * HdyFlap:click-to-close:
    *
+   * Whether the flap can be closed with a click.
+   *
+   * If %TRUE, the flap can be closed with a click on the content widget while
+   * flap is revealed. If %FALSE, clicks are passed through to the content
+   * widget.
+   *
    * Since: 1.1
    */
   props[PROP_CLICK_TO_CLOSE] =
     g_param_spec_boolean ("click-to-close",
                           _("Click to Close"),
-                          _("Click to Close"),
+                          _("Whether the flap can be closed with a click"),
                           TRUE,
                           G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
    * HdyFlap:swipe-to-open:
    *
+   * Whether the flap can be opened with a swipe gesture.
+   *
+   * The area that can be swiped depends on the #HdyFlap:transition-type value.
+   *
    * Since: 1.1
    */
   props[PROP_SWIPE_TO_OPEN] =
     g_param_spec_boolean ("swipe-to-open",
                           _("Swipe to Open"),
-                          _("Swipe to Open"),
+                          _("Whether the flap can be opened with a swipe gesture"),
                           TRUE,
                           G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
    * HdyFlap:swipe-to-close:
    *
+   * Whether the flap can be closed with a swipe gesture.
+   *
+   * The area that can be swiped depends on the #HdyFlap:transition-type value.
+   *
    * Since: 1.1
    */
   props[PROP_SWIPE_TO_CLOSE] =
     g_param_spec_boolean ("swipe-to-close",
                           _("Swipe to Close"),
-                          _("Swipe to Close"),
+                          _("Whether the flap can be closed with a swipe gesture"),
                           TRUE,
                           G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
 
@@ -1948,7 +1983,7 @@ hdy_flap_set_flap_position (HdyFlap     *self,
  * hdy_flap_get_reveal_flap:
  * @self: a #HdyFlap
  *
- * Returns: %TRUE if flap widget gets revealed.
+ * Returns: %TRUE if the flap widget is revealed, %FALSE otherwise.
  *
  * Since: 1.1
  */
@@ -1980,7 +2015,10 @@ hdy_flap_set_reveal_flap (HdyFlap  *self,
  * hdy_flap_get_reveal_duration:
  * @self: a #HdyFlap
  *
- * Returns: current reveal animation duration.
+ * Returns the amount of time (in milliseconds) that reveal transitions in @self
+ * will take.
+ *
+ * Returns: the reveal transition duration
  *
  * Since: 1.1
  */
@@ -1995,7 +2033,9 @@ hdy_flap_get_reveal_duration (HdyFlap *self)
 /**
  * hdy_flap_set_reveal_duration:
  * @self: a #HdyFlap
- * @duration: Duration for reveal animation
+ * @duration: the new duration, in milliseconds
+ *
+ * Sets the duration that reveal transitions in @self will take.
  *
  * Since: 1.1
  */
@@ -2063,11 +2103,22 @@ hdy_flap_set_fold_policy (HdyFlap           *self,
 
   self->fold_policy = policy;
 
-  if (self->fold_policy == HDY_FLAP_FOLD_POLICY_ALWAYS)
+  switch (self->fold_policy) {
+  case HDY_FLAP_FOLD_POLICY_NEVER:
+    set_folded (self, FALSE);
+    break;
+
+  case HDY_FLAP_FOLD_POLICY_ALWAYS:
     set_folded (self, TRUE);
+    break;
 
-  if (self->fold_policy == HDY_FLAP_FOLD_POLICY_NEVER)
-    set_folded (self, FALSE);
+  case HDY_FLAP_FOLD_POLICY_AUTO:
+    gtk_widget_queue_allocate (GTK_WIDGET (self));
+    break;
+
+  default:
+    g_assert_not_reached ();
+  }
 
   g_object_notify_by_pspec (G_OBJECT (self), props[PROP_FOLD_POLICY]);
 }
@@ -2076,7 +2127,10 @@ hdy_flap_set_fold_policy (HdyFlap           *self,
  * hdy_flap_get_fold_duration:
  * @self: a #HdyFlap
  *
- * Returns: current fold animation duration.
+ * Returns the amount of time (in milliseconds) that fold transitions in @self
+ * will take.
+ *
+ * Returns: the fold transition duration
  *
  * Since: 1.1
  */
@@ -2091,7 +2145,9 @@ hdy_flap_get_fold_duration (HdyFlap *self)
 /**
  * hdy_flap_set_fold_duration:
  * @self: a #HdyFlap
- * @duration: Duration for fold animation
+ * @duration: the new duration, in milliseconds
+ *
+ * Sets the duration that fold transitions in @self will take.
  *
  * Since: 1.1
  */
@@ -2113,7 +2169,11 @@ hdy_flap_set_fold_duration (HdyFlap *self,
  * hdy_flap_get_folded:
  * @self: a #HdyFlap
  *
- * Returns: %TRUE if flap widget is folded.
+ * Gets whether @self is currently folded.
+ *
+ * See #HdyFlap:fold-policy.
+ *
+ * Returns: %TRUE if @self is currently folded, %FALSE otherwise
  *
  * Since: 1.1
  */
@@ -2129,7 +2189,9 @@ hdy_flap_get_folded (HdyFlap *self)
  * hdy_flap_get_locked:
  * @self: a #HdyFlap
  *
- * Returns: %TRUE if flap widget is locked.
+ * Gets whether @self is locked.
+ *
+ * Returns: %TRUE if @self is locked, %FALSE otherwise
  *
  * Since: 1.1
  */
@@ -2144,7 +2206,13 @@ hdy_flap_get_locked (HdyFlap *self)
 /**
  * hdy_flap_set_locked:
  * @self: a #HdyFlap
- * @locked: Reveal flap
+ * @locked: the new value
+ *
+ * Sets whether @self is locked.
+ *
+ * If %FALSE, folding @self when the flap is revealed automatically closes it,
+ * and unfolding it when the flap is not revealed opens it. If %TRUE,
+ * #HdyFlap:reveal-flap value never changes on its own.
  *
  * Since: 1.1
  */
@@ -2168,7 +2236,10 @@ hdy_flap_set_locked (HdyFlap  *self,
  * hdy_flap_get_transition_type:
  * @self: a #HdyFlap
  *
- * Returns: current transition type.
+ * Gets the type of animation that will be used for reveal and fold transitions
+ * in @self.
+ *
+ * Returns: the current transition type of @self
  *
  * Since: 1.1
  */
@@ -2183,7 +2254,10 @@ hdy_flap_get_transition_type (HdyFlap *self)
 /**
  * hdy_flap_set_transition_type:
  * @self: a #HdyFlap
- * @transition_type: Duration for reveal animation
+ * @transition_type: the new transition type
+ *
+ * Sets the type of animation that will be used for reveal and fold transitions
+ * in @self.
  *
  * Since: 1.1
  */
@@ -2210,7 +2284,9 @@ hdy_flap_set_transition_type (HdyFlap               *self,
  * hdy_flap_get_click_to_close:
  * @self: a #HdyFlap
  *
- * Returns: %TRUE if flap widget is click to close.
+ * Gets whether the @self can be closed with a click.
+ *
+ * Returns: %TRUE if @self can be closed with a click
  *
  * Since: 1.1
  */
@@ -2225,7 +2301,13 @@ hdy_flap_get_click_to_close (HdyFlap *self)
 /**
  * hdy_flap_set_click_to_close:
  * @self: a #HdyFlap
- * @click_to_close: Reveal flap
+ * @click_to_close: Whether @self can be closed with a click
+ *
+ * Sets whether the @self can be closed with a click.
+ *
+ * If @click_to_close is %TRUE, @self can be closed with a click on the content
+ * widget while flap is revealed. If %FALSE, clicks are passed through to the
+ * content widget.
  *
  * Since: 1.1
  */
@@ -2259,7 +2341,9 @@ hdy_flap_set_click_to_close (HdyFlap  *self,
  * hdy_flap_get_swipe_to_open:
  * @self: a #HdyFlap
  *
- * Returns: %TRUE if flap widget is click to close.
+ * Gets whether @self can be opened with a swipe gesture.
+ *
+ * Returns: %TRUE if @self can be opened with a swipe gesture
  *
  * Since: 1.1
  */
@@ -2274,7 +2358,11 @@ hdy_flap_get_swipe_to_open (HdyFlap *self)
 /**
  * hdy_flap_set_swipe_to_open:
  * @self: a #HdyFlap
- * @swipe_to_open: Reveal flap
+ * @swipe_to_close: Whether @self can be opened with a swipe gesture
+ *
+ * Sets whether @self can be opened with a swipe gesture.
+ *
+ * The area that can be swiped depends on the #HdyFlap:transition-type value.
  *
  * Since: 1.1
  */
@@ -2300,7 +2388,9 @@ hdy_flap_set_swipe_to_open (HdyFlap  *self,
  * hdy_flap_get_swipe_to_close:
  * @self: a #HdyFlap
  *
- * Returns: %TRUE if flap widget is click to close.
+ * Gets whether @self can be closed with a swipe gesture.
+ *
+ * Returns: %TRUE if @self can be closed with a swipe gesture
  *
  * Since: 1.1
  */
@@ -2315,7 +2405,11 @@ hdy_flap_get_swipe_to_close (HdyFlap *self)
 /**
  * hdy_flap_set_swipe_to_close:
  * @self: a #HdyFlap
- * @swipe_to_close: Reveal flap
+ * @swipe_to_close: Whether @self can be closed with a swipe gesture
+ *
+ * Sets whether @self can be closed with a swipe gesture.
+ *
+ * The area that can be swiped depends on the #HdyFlap:transition-type value.
  *
  * Since: 1.1
  */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]