From 3ace68ee6f143abbcd1cc2f38f6595557dc2eaa5 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 11 May 2011 23:55:54 -0400 Subject: [PATCH] Add an initial migration chapter for GtkGrid --- docs/reference/gtk/Makefile.am | 6 + docs/reference/gtk/gtk-docs.sgml | 1 + docs/reference/gtk/images/box-expand.png | Bin 0 -> 2372 bytes docs/reference/gtk/images/box-packing.png | Bin 0 -> 3561 bytes docs/reference/gtk/images/widget-hvalign.png | Bin 0 -> 7323 bytes docs/reference/gtk/migrating-GtkGrid.xml | 185 +++++++++++++++++++ 6 files changed, 192 insertions(+) create mode 100644 docs/reference/gtk/images/box-expand.png create mode 100644 docs/reference/gtk/images/box-packing.png create mode 100644 docs/reference/gtk/images/widget-hvalign.png create mode 100644 docs/reference/gtk/migrating-GtkGrid.xml diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index a9bdd747c..7c643b55a 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -124,6 +124,7 @@ content_files = \ migrating-2to3.xml \ migrating-checklist.sgml \ migrating-GtkApplication.xml \ + migrating-GtkGrid.xml \ migrating-GtkStyleContext.xml \ objects_grouped.sgml \ osx.sgml \ @@ -146,6 +147,7 @@ expand_content_files = \ migrating-2to3.xml \ migrating-checklist.sgml \ migrating-GtkApplication.xml \ + migrating-GtkGrid.xml \ migrating-GtkStyleContext.xml \ question_index.sgml \ text_widget.sgml \ @@ -277,6 +279,8 @@ HTML_IMAGES = \ $(srcdir)/images/appchooserbutton.png \ $(srcdir)/images/appchooserdialog.png \ $(srcdir)/images/assistant.png \ + $(srcdir)/images/box-packing.png \ + $(srcdir)/images/box-expand.png \ $(srcdir)/images/button.png \ $(srcdir)/images/check-button.png \ $(srcdir)/images/color-button.png \ @@ -296,6 +300,7 @@ HTML_IMAGES = \ $(srcdir)/images/label.png \ $(srcdir)/images/link-button.png \ $(srcdir)/images/list-and-tree.png \ + $(srcdir)/images/lockbutton.png \ $(srcdir)/images/lockbutton-locked.png \ $(srcdir)/images/lockbutton-unlocked.png \ $(srcdir)/images/lockbutton-sorry.png \ @@ -329,6 +334,7 @@ HTML_IMAGES = \ $(srcdir)/images/layout-rltb.png \ $(srcdir)/images/layout-tblr.png \ $(srcdir)/images/layout-tbrl.png \ + $(srcdir)/images/widget-hvalign.png \ $(srcdir)/images/window-default.png \ $(srcdir)/images/hello-world.png \ $(srcdir)/images/grid-packing.png \ diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index a2bd08298..11d14ab2d 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -355,6 +355,7 @@ + diff --git a/docs/reference/gtk/images/box-expand.png b/docs/reference/gtk/images/box-expand.png new file mode 100644 index 0000000000000000000000000000000000000000..e5af4f285a6f38344a52b25ae1c5a8715b2a2940 GIT binary patch literal 2372 zcma);YdjN<9>$l@O#U^IP;N~wxyv&oCf8y@NLVUnuDON~lG`6eOj3)~ zP$P5OjB+<-+lCC z0010Bz^~YcJzu0pS)ag299fRij?w-?yd29X7$b`24lI)~Qz+nSlWM~c5()+z+So3s zAjN?Kc_~o2a@R%Bibqrq)eJptaN2Nz_Qy@p4g8%bA){yp5D@&5kbSv6d@1=%@I^kH zY%4mQF;lBG+{9e%Sz1-fD|}U6enc7$Xa`T;VgUeW52x~+{(m50G}E1x%H(}oLwO$d z_F6)tvn}cql#Fb|lDw4e@jaw?2qSZCD^9PAzc_mwctI?QFA*CO!VWW7kLZA;ni{v* zB1-NEL)Z4cf17t$#iJ zM>LQ%CsUNtlRSQem)FcH1NDAA->fuOTvyJYC1GOnWtymbcT~_EMCkboco{f#dY6L^ zWEJ7D63H81Yg`HIgiBgF{H#f_E?odHB3Q7NDFi^l)3JP3~Bu}*|@12bNL6YuXv-TBrdKTUcBLf7-q*yiYKnDmfa6yZbgmM z75~~TTwKf3JL|QOxtoK;_`F`CZEYMA(6MrG{1NR?EMI-{cW$~c1SX>5Mr+2fhI4&T zl7%Vbc$1j2#86FmXmPy|m z%&7$I9Jl4|*!;ab%g539x!+e3w~L=!r+9(UwQobi@L@&@-Hw z@_mWk?mPE_`jn>>z!!%`Qz6Z_Nvs;z4|}8}@iypKku*z?JLdRGhAGILeCv$H_5!#W z`?Rw1Jj~m{-u@=y_C^Dyf9(E3pxCoqszR;`{v9S6%=c&m4w zDuhO;82U@XGe?{KrhuTj$MThGz=ZEfb=xeh*c}F9J{unH3 zAUBJR7Bz;cn>do_ToLP03PiNguQ@fTh1fhiG6K!~iZhNFZES3eSCufOYpSVPJKB%W z&--vnkO2ODQ&;yi;YMZ_YAA9;#mGk0t#x*m`I6BRIpyQK zu**>;)I7l(q~w%d+!5ra^p}LK%@4G#xH)E9!A>eGUp%jz2x9w* zjZkTXp}HPAvk(<&alymAhFcnbZ2UM($Vk1=4P6ubW6NY!;h!z$yKtS1q;kg*JhN^3 zBfN77wPUuV8aS))f(@t0k;(J$R^#lxelsf)*VNM$+;FC<+ z$0aO*VXQp%^0Y&`$W2e~RIQ27i4zT7*|i^6EWX*CDUWv#N#}-j1hK|AJp6MzwC>yOg7}_mPBsqJ^DKrsHYRhV zr6oRZzZ;sZAjs$M@8`9(rKhL2CNJb-Z2UH55M1Baz|0m}`g}@U)pB$5Zp1Pte6PXl zDGnwgBJv?eb1M?siCa2^p8jKsbcnG$=Zp6XM>{;Y`?RXW^Tz0o_fnnt+FCTnE^6}i zfG>5gtfV2>ZMIej)Zy&^hV5u~_s zqKjmWvd3IJ`fJWkx1OeoES(mBAFT`WVx=2d34yR0NY`6)pYkm&2@P^DU0zHKb#)9Q zt0@<>wGi)HpXWcv_RAFAf%_7YlQK;qDk>_}zJr(~sL1PMCweJPv!+jy5Qve0$zuEu zsnq=W2{5=(K76D6*+97gT!wyOXTLk{ooQ|C$w=*Qlgm9*P-7N>jujC-B>hzh!p#q=U*?=$xH}=Ra^@`+@b&F0a)!&cez55 svz*#l>#7sZQl}mqBE)oY{ZFhYq?$qa_{~4R<&W<uvmnQS92)M2`@^Kz5FU-~)B}f=;<4{Pd2C=egm!((-M9-?7_xQr2WsUEY zvPSEfUAQa`d9(ESnc(FYH@;6-;b}NTz@fA7ET-1_lQ?2mvmrGrQa37dUfB%8%gJE0bD27(D-w zY>Y4$#~R>o&h+%?6qyQ40h|Def0D;xS;Y0Pbq^$)+=Ry*qvfMpN*%@;0srTUw*q+C z0&LdW2?K_7_|{UFg-br0ueW(!DOS{%(jKz4pG3jUL_|hR_vyOKdhdL>|MVD}6S>Z) z3#-E6!qpGIO57*?*;7_lIGq2!yWDZ8u)X-v!3MP^2_n5+((HQ z6!awcWURlx+;9d0h9ge?O~a@vI^Wa=Aq_mj_Tn}$Q@>UBCQPJ@T_V`dS&N9wRPWi` z)2dX0LeU14>67KC-pEKLU+VPKbO>$SZ9JZXVf%4DY`fNI*3`zP3mkmQE!ycJyK>8} zL)73hdCit+*Y3Q!r~zNl+A2pWf&S{GxgvdRJM@G1VQg96><&d<-&Y2{6}}}p%4ggZ zNHCkZprnKsZ1JIQEf`vqs}&bc%E-z#DvaOan#W&nYh9^qkIC{7ksDq_)Jv3> zO1Y|4WL;w{d?$2kOq)F7Y2K-sjg^&=zKc+Ro{KtJCgL}*zZUv2NA?uFE83?b^r8I| z5bIT{n_l_CywSl8atUFiRHJLL&BfgvN}1UcJlPojKm;Q;=()`5>XmB3R zJa06*Og6m_eTS9*^v(NT=ovJ3Zv?_x>Jv6=X1Qb=lb+ri8)uTQ+2j(IMkT!*c2;c( zQw!YE4V>#F2c04qBq5dZ)KrbY|pY#OB00}qN$9o~$qxf4dGl7q&gS=j29tR1{m zQWEuK&|Yb@#moWsCZ)OAxw*O7*@(%GJMgskqXoG~Q>ZJ$?O~g2_T0p|+W9L92k~E= zIc)8)I`N=T>a4a5|B&l#A}j>^-O*1(;O9bhbT~dFgqZPyNL;>dl9QYBNljF`@4Z}UU_NJk%gaWSmlX}RWFy|$JP zu2jVQJQVR|MVXtMqZvJo9+~|7G!>y$liK`+4L-tWX$v=Z5h)od`*tvCj%cvgIcDR9 zsLTMz*g^;a&veDV$dh_{^8TX0yk%Ppm-s&okVv-TsZxBy!zYWVp%a>RxZbnRQ&WBM zIk}hvM@vRIeRHlcc)fdP;_HO_h*~yQBZ`t`!pX@Owq+}?3=3(F++R<9D85v$I(~1X z=47?3Y^P8G!;klMlov2Q>bfN41D&T(NU5V90)7tM0D0dZE5s_PG*Nv(AY_#lP`hIL z?%$3G`rC&xDKB0nrzF4U9nDiWw!6fCQFwqDWo_-{>porfn>|TT`EfWyn^`3JYN3?+ z&|$^`{9~HA&;d_OP^YlMlZ>kQpg=hX(m`2yc|z|}t4fQ5h{zsXYlr`yV8zoyZ9DPv zswyfsE^xNlj=0{Qno;3m>+S2)_5AE8kDO7G6|C?DBiPm@iY;}ga7@w^5ag?K=5KM8 zxZC+{U2@YTW)+XWD=sb$>Flv6Tb0!WE@>&k1d=i}>Sh8L>+w%*C~~kP>Hp#J6VjB7 zj7;-!nfibu@>D#_*qB_qNZG_)FF#TS8`J-E?YMZtogD!vb_*sKk8ji@Fxo*ULd`O; z|3&!!L;3aexr))w#|YDRVWsSSTD=v%Sq5e8YbJ%0_E!zY6siZ3cDl}mYv`mj_(hD$ zlW6?|Cuk8EN37xl2peVp+u2LWh6Y?W4CRdTHO;Lo+_n&lI>E=T5`h*M5{IMq_X8{} zu*prol_%cs(SOB*eCOMwPr7$Z3=PrMH69Og)ts~C;!P#f-CW&Q?K=_Xs2TD?r02uu z`T4?FivalGuZpSUOOW-|rJ}#b2(+Eu-NpYv5V9f$_n{(HSAaasMlJ zfNN=)KW$4fvsGNJzc1d(7J;xgYf!ndKGK2F!Y%CgLl=j-3Nzkjf<)%KhmGW}Q;qMr zTQX8hSWzep1eLXnR&2F{WWA@2wr1qc&w@8sze+srj^If&H?wNHp&0S=GfT@aUlh`k zS;wS2=+q2>U1xR@Jft46-}5D}zg+TuXWaH^Q!PRQ7z-Xm3o65aqeuR}Om2+SBneYa zFWTEP+X&fbnu$qepT+T^-Z(GozDg(kKZn;OoIE5vBtpsSLg8Y`zlhDtbSgOSW$R=$nrhObZt=I zm{{Dxq;KixfFpQJLbg#<$$e%OBzm#sm;X@lC7GcHwzoH~N$cP2#-PNeAPmrnoj;kV{g5Fe8+j5N9;AWU>z^$21a9hy=REj_ z`or1pH;_SkAv=HB{rHEJPkZ3K`@SI zlk-{lslc1G;>ZvaB1|wmN@=5}%0DlwKO(33({)}^Lt{lp^6s>#i|c%+a*7>AR6G1& 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 + + + + Migrating from other containers to GtkGrid + + + #GtkGrid is an attempt to write a comprehensive, legacy-free, + box-layout container that is flexible enough to replace #GtkBox, + #GtkTable, #GtkAlignment and the like. + + + + The layout model of GtkGrid is to arrange its children in rows and + columns (children can span multiple rows or columns, too). This is + done by assigning positions (and sizes) on a two-dimentions grid that + stretches arbitrarily far in all directions. + + +
+ + GtkBox versus GtkGrid: packing + + + GtkBox works by arranging child widgets in a single line, either + horizontally or vertically. It allows packing children from the + beginning or end, using gtk_box_pack_start() and gtk_box_pack_end(). + + + + + + A simple box + + box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0); + + gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("One"), FALSE, FALSE, 0); + gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("Two"), FALSE, FALSE, 0); + + This can be done with #GtkGrid as follows: + + grid = gtk_grid_new (); + + child1 = gtk_label_new ("One"); + gtk_grid_attach (GTK_GRID (grid), child1, 0, 0, 1, 1); + child2 = gtk_label_new ("Two"); + gtk_grid_attach_next_to (GTK_GRID (grid), child2, child1, GTK_POS_RIGHT, 1, 1); + + + And similarly for gtk_box_pack_end(). In that case, you + would use #GTK_POS_LEFT to place the grid children from + left to right. + + + + + One difference to keep in mind is that the gtk_box_pack_start/pack_end + functions allow you to place an arbitrary number of children from + either end without ever 'colliding in the middle'. With GtkGrid, you + have to leave enough space between the two ends, if you want to combine + packing from both ends towards the middle. In practice, this should be + easy to avoid; and GtkGrid simply ignores entirely empty rows or + columns for layout and spacing. + + + On the other hand, GtkGrid is more flexible in that its grid extends + indefinitively in both directions — there is no problem with + using negative numbers for the grid positions. So, if you discover + that you need to place a widget before your existing arrangement, + you always can. + +
+ +
+ GtkBox versus GtkGrid: sizing + + + When adding a child to a GtkBox, there are two hard-to-remember + parameters (child properties, more exactly) named expand and fill + that determine how the child size behaves in the main direction + of the box. If expand is set, the box allows the position occupied + by the child to grow when extra space is available. If fill is + also set, the extra space is allocated to the child widget itself. + Otherwise it is left 'free'. + There is no control about the 'minor' direction; children + are always given the full size in the minor direction. + + + + + + GtkGrid does not have any custom child properties for controlling + size allocation to children. Instead, it fully supports the newly + introduced #GtkWidget:hexpand, #GtkWidget:vexpand, #GtkWidget:halign + and #GtkWidget:valign properties. + + + The #GtkWidget:hexpand and #GtkWidget:vexpand properties operate + in a similar way to the expand child properties of #GtkBox. As soon + as a column contains a hexpanding child, GtkGrid allows the column + to grow when extra space is available (similar for rows and vexpand). + In contrast to GtkBox, all the extra space is always allocated + to the child widget, there are no 'free' areas. + + + To replace the functionality of the fill child properties, you can + set the #GtkWidget:halign and #GtkWidget:valign properties. An + align value of #GTK_ALIGN_FILL has the same effect as setting fill + to %TRUE, a value of #GTK_ALIGN_CENTER has the same effect as setting + fill to %FALSE. The image below shows the effect of various combinations + of halign and valign. + + + + + + Expansion and alignment + + box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0); + + gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("One"), TRUE, FALSE, 0); + gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("Two"), TRUE, TRUE, 0); + + This can be done with #GtkGrid as follows: + + grid = gtk_grid_new (); + + child1 = gtk_label_new ("One"); + gtk_widget_set_hexpand (child1, TRUE); + gtk_widget_set_halign (child1, GTK_ALIGN_CENTER); + gtk_grid_attach (GTK_GRID (grid), child1, 0, 0, 1, 1); + child2 = gtk_label_new ("Two"); + gtk_widget_set_hexpand (child2, TRUE); + gtk_widget_set_halign (child1, GTK_ALIGN_FILL); + gtk_grid_attach_next_to (GTK_GRID (grid), child2, child1, GTK_POS_RIGHT, 1, 1); + + + + One difference between the new GtkWidget expand properties and + the GtkBox child property of the same name is that widget expandability + is 'inherited' from children. What this means is that a container + will become itself expanding as soon as it has + an expanding child. This is typically what you want, it lets + you e.g. mark the content pane of your application window as + expanding, and all the intermediate containers between the + content pane and the toplevel window will automatically do + the right thing. This automatism can be overridden at any + point by setting the expand flags on a container explicitly. + + + Another difference between GtkBox and GtkGrid with respect to + expandability is when there are no expanding children at all. + In this case, GtkBox will forcibly expand all children whereas + GtkGrid will not. In practice, the effect of this is typically + that a grid will 'stick to the corner' when the toplevel + containing it is grown, instead of spreading out its children + over the entire area. The problem can be fixed by setting some + or all of the children to expand. + + + + When you set the #GtkBox:homogeneous property on a GtkBox, + it reserves the same space for all its children. GtkGrid does + this in a very similar way, with #GtkGrid:row-homogeneous and + #GtkGrid:column-homogeneous properties which control whether + all rows have the same height and whether all columns have + the same width. + +
+ + + -- 2.43.2