src/ui/pack.h

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2 /** @file
   3  * Helpers for using Gtk::Boxes, encapsulating large changes between GTK3 & GTK4
   4  */
   5 /*
   6  * Authors:
   7  *   Daniel Boles <dboles.src+inkscape@gmail.com>
   8  *
   9  * Copyright (C) 2023 Daniel Boles
  10  * Released under GNU GPL v2+, read the file 'COPYING' for more information.
  11  */
  12
  13 #ifndef SEEN_UI_BOX_PACK_H
  14 #define SEEN_UI_BOX_PACK_H
  15
  16 namespace Gtk {
  17 class Box;
  18 class Widget;
  19 } // namespace Gtk
  20
  21 namespace Inkscape::UI {
  22
  23 /// Equivalent to GTK3ʼs Gtk::PackOptions
  24 enum class PackOptions {shrink, expand_padding, expand_widget};
  25
  26 /// Adds child to box, packed with reference to the start of box.
  27 /// The child is packed after any other child packed with reference to the start of box.
  28 ///
  29 /// Our pack_*() functions aim to replace GTKʼs Box.pack_start() in a GTK4-ready
  30 /// way, so code built against GTK3 can swap to our functions and afterward will
  31 /// not have need rewritten in migrating to GTK4. If writing new code you should
  32 /// probably avoid using these if you can, as they cannot be converted from C++
  33 /// to .ui for instance. Instead, set properties on child widgets (not using the
  34 /// GTK3-only child properties!) and use Box.add() in GTK3 or .append() in GTK4.
  35 ///
  36 /// Internally, the list of children in the Box is maintained in the order of:
  37 /// * widgets added by our pack_start(), in the same order of the calls thereto;
  38 /// * …widgets added by our pack_end() in the *opposite* order of calls thereto.
  39 ///
  40 /// The expand, fill and padding are implemented by setting relevant [hv]expand,
  41 /// [hv]align and margin-* properties on the child, instead of GTK3 child props.
  42 ///
  43 /// @param child The Gtk::Widget to be added to the box.
  44 ///
  45 /// @param expand TRUE if the new child is to be given extra space allocated to
  46 ///     box. The extra space will be divided evenly between all children that
  47 ///     use this option.
  48 ///     This is implemented by setting the childʼs relevant [hv]expand property.
  49 ///     Note that there’s a subtle but important difference between GtkBox‘s
  50 ///     expand and fill child properties and the ones in GtkWidget: setting
  51 ///     GtkWidget:hexpand or GtkWidget:vexpand to TRUE will propagate up the
  52 ///     widget hierarchy, so a pixel-perfect port might require you to reset the
  53 ///     expansion flags to FALSE in a parent widget higher up the hierarchy, or
  54 ///     to set the child to not expand (shrink). Our pack_*() functions do not
  55 ///     attempt to do workaround this for you, as that might cause NEW problems.
  56 ///
  57 /// @param fill TRUE if space given to child by the expand option is actually
  58 ///     allocated to child, rather than just padding it. This parameter has no
  59 ///     effect if expand is set to FALSE. A child is always allocated the full
  60 ///     height of a horizontal GtkBox and the full width of a vertical GtkBox.
  61 ///     This option affects the other dimension.
  62 ///     This is implemented by setting the childʼs relevant [hv]align prop to
  63 ///     ALIGN_FILL if fill is TRUE, else to START or END to match the pack type.
  64 ///
  65 /// @param padding Extra space in pixels to put between this child and its
  66 ///     neighbors, over and above the global amount specified by GtkBox:spacing
  67 ///     property. If child is a widget at one of the reference ends of box, then
  68 ///     padding pixels are also put between child and the reference edge of box.
  69 ///     This is implemented by adding to the childʼs relevant margin-* props.
  70 void pack_start(Gtk::Box &box, Gtk::Widget &child, bool expand, bool fill,
  71                 unsigned padding = 0);
  72
  73 /// Adds child to box, packed with reference to the start of box.
  74 /// @param options The PackOptions to use, which are decomposed into booleans of
  75 ///     whether to expand or fill and passed to the other overload; see its doc.
  76 void pack_start(Gtk::Box &box, Gtk::Widget &child,
  77                 PackOptions options = PackOptions::expand_widget,
  78                 unsigned padding = 0);
  79
  80 /// Adds child to box, packed with reference to the end of box.
  81 /// The child is packed after (away from end of) any other child packed with reference to the end of box.
  82 /// See the documentation of pack_start() for details of the parameters.
  83 void pack_end(Gtk::Box &box, Gtk::Widget &child, bool expand, bool fill,
  84               unsigned padding = 0);
  85
  86 /// Adds child to box, packed with reference to the end of box.
  87 /// The child is packed after (away from end of) any other child packed with reference to the end of box.
  88 /// @param options The PackOptions to use, which are decomposed into booleans of
  89 ///     whether to expand or fill and passed to the other overload; see its doc.
  90 void pack_end(Gtk::Box &box, Gtk::Widget &child,
  91               PackOptions options = PackOptions::expand_widget,
  92               unsigned padding = 0);
  93
  94 } // namespace Inkscape::UI
  95
  96 #endif // SEEN_UI_BOX_PACK_H
  97
  98 /*
  99   Local Variables:
 100   mode:c++
 101   c-file-style:"stroustrup"
 102   c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
 103   indent-tabs-mode:nil
 104   fill-column:99
 105   End:
 106 */
 107 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:fileencoding=utf-8:textwidth=99 :